@lessonkit/lxpack 0.9.3 → 1.0.1

package/dist/index.js

@@ -1,28 +1,78 @@
 import {
   telemetryEventToLessonkit
-} from "./chunk-PSUSESH3.js";
+} from "./chunk-DYQI222N.js";
 
 // src/validateDescriptor.ts
 import { validateId } from "@lessonkit/core";
 
 // src/spaPath.ts
-import { resolve, sep } from "path";
+import { realpathSync } from "fs";
+import { isAbsolute, 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;
-  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 = 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 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 win32.relative(rootResolved, targetResolved);
+  }
+  return 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("..") && !isAbsolute(rel);
+}
 
 // src/theme.ts
 import { getPresetTheme, themeToCssVariables } from "@lessonkit/themes";
@@ -42,6 +92,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 = validateId(input.courseId, "courseId");
   if (!course.ok) throw new Error("normalizeDescriptor called with invalid courseId");
@@ -75,6 +189,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 = validateId(input.courseId, "courseId");
   if (!course.ok) issues.push(...course.issues.map((i) => ({ path: i.path, message: i.message })));
@@ -198,7 +337,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)"
@@ -210,7 +349,7 @@ function validateDescriptor(input) {
 }
 
 // src/validateProjectPaths.ts
-import { isAbsolute, resolve as resolve2 } from "path";
+import { isAbsolute as isAbsolute2, resolve as resolve2 } from "path";
 function validatePathField(value, fieldPath, projectRoot, issues) {
   if (!isSafeRelativeSpaPath(value)) {
     issues.push({
@@ -220,7 +359,7 @@ function validatePathField(value, fieldPath, projectRoot, issues) {
     return;
   }
   try {
-    assertResolvedPathUnderRoot(projectRoot, resolve2(projectRoot, value));
+    assertRealPathUnderRoot(projectRoot, resolve2(projectRoot, value));
   } catch {
     issues.push({
       path: fieldPath,
@@ -248,16 +387,16 @@ function resolveSafePackageOutputOverride(projectRoot, override) {
   if (!trimmed) {
     throw new Error("output override must be a non-empty path");
   }
-  if (isAbsolute(trimmed)) {
+  if (isAbsolute2(trimmed)) {
     const resolved2 = resolve2(trimmed);
-    assertResolvedPathUnderRoot(root, resolved2);
+    assertRealPathUnderRoot(root, resolved2);
     return resolved2;
   }
   if (!isSafeRelativeSpaPath(trimmed)) {
     throw new Error(`unsafe output path: ${override}`);
   }
   const resolved = resolve2(root, trimmed);
-  assertResolvedPathUnderRoot(root, resolved);
+  assertRealPathUnderRoot(root, resolved);
   return resolved;
 }
 
@@ -304,6 +443,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") {
@@ -341,7 +492,7 @@ function descriptorToInterchange(descriptor) {
       type: "spa",
       path: l.path
     })),
-    tracking: descriptor.tracking,
+    tracking: mapDescriptorTracking(descriptor.tracking),
     runtime: runtime ? {
       theme: runtime.theme,
       cssVariables: runtime.cssVariables
@@ -351,12 +502,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 +515,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 };
   }
@@ -383,7 +539,19 @@ async function resolveSpaDirs(options) {
     }
     const resolved = projectRoot ? resolve3(projectRoot, src) : resolve3(src);
     if (projectRoot) {
-      assertResolvedPathUnderRoot(resolve3(projectRoot), resolved);
+      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;
   }
@@ -401,7 +569,7 @@ async function writeLxpackProject(options) {
   const descriptor = validation.descriptor;
   const outDir = resolve4(options.outDir);
   if (options.projectRoot) {
-    assertResolvedPathUnderRoot(resolve4(options.projectRoot), outDir);
+    assertRealPathUnderRoot(resolve4(options.projectRoot), outDir);
   }
   const spaDirs = await resolveSpaDirs({ ...options, descriptor });
   const interchange = descriptorToInterchange(descriptor);
@@ -419,78 +587,36 @@ 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
-  });
-}
-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
-  });
-}
-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 = resolve5(writeOpts.outDir);
-  const projectRoot = writeOpts.projectRoot ? resolve5(writeOpts.projectRoot) : void 0;
+
+// src/packaging/validateInputs.ts
+import { isAbsolute as isAbsolute3, 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) {
-    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 {
@@ -500,10 +626,18 @@ async function packageLessonkitCourse(options) {
       issues: [{ path: "outputBaseDir", message: `unsafe outputBaseDir: ${outputBaseDir}` }]
     };
   }
-  if (projectRoot && output) {
-    const resolvedOutput = resolve5(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 = resolve5(projectRoot, outputBaseDir);
     try {
-      assertResolvedPathUnderRoot(projectRoot, resolvedOutput);
+      assertRealPathUnderRoot(projectRoot, resolvedOutputBase);
     } catch (err) {
       return {
         ok: false,
@@ -511,28 +645,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 = resolve5(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(join2(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("..") || isAbsolute3(rel)) {
+    return artifactPath;
+  }
+  if (!rel) return outDir;
+  if (/^[a-zA-Z]:[/\\]/.test(outDir)) {
+    return win322.join(outDir, rel.replace(/\//g, win322.sep));
+  }
+  return join3(outDir, rel);
+}
+
+// src/packaging/promote.ts
+import * as fsp from "fs/promises";
+import { randomUUID } from "crypto";
+import { dirname, join as join4 } from "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 = dirname(outDir);
+  const tmpPromote = await fsp.mkdtemp(join4(parent, ".lk-promote-"));
+  await renameOrCopy(stagingDir, tmpPromote);
+  const hadOutDir = await pathExists(outDir);
+  const backup = hadOutDir ? await fsp.mkdtemp(join4(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 = join4(parent, `.lk-failed-promote-${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 = join4(parent, `.lk-failed-promote-${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
+import * as fsp2 from "fs/promises";
+import { dirname as dirname2, join as join5 } 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(join5(tmpdir(), "lessonkit-lxpack-"));
   try {
     let spaDirs;
     try {
@@ -540,8 +798,7 @@ async function packageLessonkitCourse(options) {
     } catch (err) {
       return {
         ok: false,
-        courseDir: outDir,
-        target,
+        stagingDir,
         issues: [
           {
             path: "spaDirs",
@@ -552,8 +809,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(join5(stagingDir, outputBase), { recursive: true });
+    const defaultOutput = output ?? (dir ? join5(outputBase, target) : join5(outputBase, `course-${target}.zip`));
     const build = await packageLessonkit({
       interchange,
       spaDirs,
@@ -566,15 +823,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,
@@ -583,48 +834,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 = 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(dirname2(outDir), { recursive: true });
+}
+
+// src/packageCourse.ts
+async function validateLessonkitProject(options) {
+  return validateCourse({
+    courseDir: resolve6(options.courseDir),
+    target: options.target
+  });
+}
+async function buildLessonkitProject(options) {
+  const buildOptions = {
+    courseDir: resolve6(options.courseDir),
+    target: options.target,
+    output: options.output,
+    dir: options.dir,
+    outputBaseDir: options.outputBaseDir,
+    assessments: options.assessments
+  };
+  return 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(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" }] };
   }
 }
 
@@ -643,21 +1102,29 @@ 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,
+  validateDescriptorForTarget,
   validateLessonkitProject,
+  validatePackageInputs,
   validateProjectPaths,
   writeLxpackProject
 };