@lessonkit/lxpack 0.6.0

package/dist/index.cjs

@@ -0,0 +1,577 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  assessmentDescriptorToLxpack: () => assessmentDescriptorToLxpack,
+  buildLessonkitProject: () => buildLessonkitProject,
+  descriptorToInterchange: () => descriptorToInterchange,
+  extractAssessments: () => extractAssessments,
+  mapLessonkitIds: () => mapLessonkitIds,
+  packageLessonkitCourse: () => packageLessonkitCourse,
+  resolveSpaLessons: () => resolveSpaLessons,
+  themeToLxpackRuntime: () => themeToLxpackRuntime,
+  validateDescriptor: () => validateDescriptor,
+  validateLessonkitProject: () => validateLessonkitProject,
+  writeLxpackProject: () => writeLxpackProject
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/validateDescriptor.ts
+var import_core = require("@lessonkit/core");
+
+// src/spaPath.ts
+var import_node_path = require("path");
+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(/[/\\]/);
+  if (segments.some((s) => s === "..")) return false;
+  return true;
+}
+function assertResolvedPathUnderRoot(root, target) {
+  const rootResolved = (0, import_node_path.resolve)(root);
+  const targetResolved = (0, import_node_path.resolve)(target);
+  const prefix = rootResolved.endsWith(import_node_path.sep) ? rootResolved : rootResolved + import_node_path.sep;
+  if (targetResolved !== rootResolved && !targetResolved.startsWith(prefix)) {
+    throw new Error(`unsafe path escapes project root: ${target}`);
+  }
+}
+
+// src/validateDescriptor.ts
+function normalizeDescriptor(input) {
+  const course = (0, import_core.validateId)(input.courseId, "courseId");
+  if (!course.ok) throw new Error("normalizeDescriptor called with invalid courseId");
+  return {
+    ...input,
+    courseId: course.id,
+    title: input.title.trim(),
+    version: input.version?.trim() || void 0,
+    spaLessonId: input.spaLessonId?.trim() || void 0,
+    lessons: input.lessons.map((lesson) => {
+      const idResult = (0, import_core.validateId)(lesson.id, "lessonId");
+      if (!idResult.ok) throw new Error("normalizeDescriptor called with invalid lesson id");
+      return {
+        ...lesson,
+        id: idResult.id,
+        title: lesson.title.trim(),
+        spaPath: lesson.spaPath?.trim() || void 0
+      };
+    }),
+    assessments: input.assessments?.map((assessment) => {
+      const check = (0, import_core.validateId)(assessment.checkId, "checkId");
+      if (!check.ok) throw new Error("normalizeDescriptor called with invalid checkId");
+      return {
+        ...assessment,
+        checkId: check.id,
+        question: assessment.question.trim(),
+        choices: assessment.choices.map((c) => c.trim()).filter((c) => c.length > 0),
+        answer: assessment.answer.trim()
+      };
+    })
+  };
+}
+function validateDescriptor(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 })));
+  if (!input.title?.trim()) {
+    issues.push({ path: "title", message: "title is required" });
+  }
+  if (!input.lessons?.length) {
+    issues.push({ path: "lessons", message: "at least one lesson is required" });
+  }
+  if (input.layout === "single-spa" && (input.lessons?.length ?? 0) > 1) {
+    issues.push({
+      path: "lessons",
+      message: "single-spa layout packages one SPA lesson; remove extra lesson entries or use per-lesson-spa"
+    });
+  }
+  const lessonIds = /* @__PURE__ */ new Set();
+  const spaPaths = /* @__PURE__ */ new Set();
+  for (const [index, lesson] of (input.lessons ?? []).entries()) {
+    const path = `lessons[${index}]`;
+    const lessonResult = (0, import_core.validateId)(lesson.id, `${path}.id`);
+    if (!lessonResult.ok) {
+      issues.push(...lessonResult.issues.map((i) => ({ path: i.path, message: i.message })));
+    } else if (lessonIds.has(lessonResult.id)) {
+      issues.push({ path: `${path}.id`, message: "duplicate lesson id" });
+    } else {
+      lessonIds.add(lessonResult.id);
+    }
+    if (!lesson.title?.trim()) {
+      issues.push({ path: `${path}.title`, message: "lesson title is required" });
+    }
+    if (input.layout === "per-lesson-spa") {
+      const spaPath = lesson.spaPath?.trim();
+      if (!spaPath) {
+        issues.push({
+          path: `${path}.spaPath`,
+          message: "spaPath is required for per-lesson-spa layout"
+        });
+      } else if (!isSafeRelativeSpaPath(spaPath)) {
+        issues.push({
+          path: `${path}.spaPath`,
+          message: "spaPath must be a relative path without '..' segments or absolute prefixes"
+        });
+      } else if (spaPaths.has(spaPath)) {
+        issues.push({ path: `${path}.spaPath`, message: "duplicate spaPath" });
+      } else {
+        spaPaths.add(spaPath);
+      }
+    }
+  }
+  if (input.layout === "single-spa" && input.spaLessonId?.trim()) {
+    const spaId = input.spaLessonId.trim();
+    const spaResult = (0, import_core.validateId)(spaId, "spaLessonId");
+    if (!spaResult.ok) {
+      issues.push(...spaResult.issues.map((i) => ({ path: i.path, message: i.message })));
+    } else if (!lessonIds.has(spaResult.id)) {
+      issues.push({
+        path: "spaLessonId",
+        message: "spaLessonId must match a lesson id in lessons"
+      });
+    }
+  }
+  const checkIds = /* @__PURE__ */ new Set();
+  for (const [index, assessment] of (input.assessments ?? []).entries()) {
+    const path = `assessments[${index}]`;
+    const check = (0, import_core.validateId)(assessment.checkId, `${path}.checkId`);
+    if (!check.ok) {
+      issues.push(...check.issues.map((i) => ({ path: i.path, message: i.message })));
+    } else if (checkIds.has(check.id)) {
+      issues.push({ path: `${path}.checkId`, message: "duplicate checkId" });
+    } else {
+      checkIds.add(check.id);
+    }
+    if (!assessment.question?.trim()) {
+      issues.push({ path: `${path}.question`, message: "question is required" });
+    }
+    const trimmedChoices = (assessment.choices ?? []).map((c) => c.trim()).filter((c) => c.length > 0);
+    if (!trimmedChoices.length) {
+      issues.push({
+        path: `${path}.choices`,
+        message: "at least one non-empty choice is required"
+      });
+    }
+    if (!assessment.answer?.trim()) {
+      issues.push({ path: `${path}.answer`, message: "answer is required" });
+    } else if (trimmedChoices.length && !trimmedChoices.includes(assessment.answer.trim())) {
+      issues.push({ path: `${path}.answer`, message: "answer must match a choice" });
+    }
+    const passingScore = assessment.passingScore;
+    if (passingScore !== void 0) {
+      if (!(passingScore > 0)) {
+        issues.push({
+          path: `${path}.passingScore`,
+          message: "passingScore must be greater than 0"
+        });
+      } else if (trimmedChoices.length && passingScore > trimmedChoices.length) {
+        issues.push({
+          path: `${path}.passingScore`,
+          message: "passingScore must not exceed the number of choices"
+        });
+      }
+    }
+  }
+  if (issues.length) return { ok: false, issues };
+  return { ok: true, descriptor: normalizeDescriptor(input) };
+}
+
+// src/mapIds.ts
+var import_core2 = require("@lessonkit/core");
+function mapLessonkitIds(descriptor) {
+  const courseId = (0, import_core2.assertValidId)(descriptor.courseId, "courseId");
+  const lessonIds = descriptor.lessons.map((l) => (0, import_core2.assertValidId)(l.id, "lessonId"));
+  const checkIds = (descriptor.assessments ?? []).map(
+    (a) => (0, import_core2.assertValidId)(a.checkId, "checkId")
+  );
+  return { courseId, lessonIds, checkIds };
+}
+
+// src/theme.ts
+var import_themes = require("@lessonkit/themes");
+function themeToLxpackRuntime(input) {
+  const theme = input.theme ?? (0, import_themes.getPresetTheme)(input.preset ?? "default");
+  const raw = (0, import_themes.themeToCssVariables)(theme);
+  const cssVariables = {};
+  for (const [key, value] of Object.entries(raw)) {
+    cssVariables[key] = String(value);
+  }
+  return {
+    theme: theme.name,
+    cssVariables
+  };
+}
+
+// src/interchange.ts
+function resolveSpaLessons(descriptor) {
+  const mapped = mapLessonkitIds(descriptor);
+  if (descriptor.layout === "single-spa") {
+    const spaLessonId = descriptor.spaLessonId ?? mapped.lessonIds[0] ?? "main";
+    const firstLesson = descriptor.lessons.find((l) => l.id === spaLessonId);
+    return [
+      {
+        id: spaLessonId,
+        title: firstLesson?.title ?? descriptor.title,
+        path: "dist"
+      }
+    ];
+  }
+  return descriptor.lessons.map((lesson) => ({
+    id: lesson.id,
+    title: lesson.title,
+    path: lesson.spaPath
+  }));
+}
+function descriptorToInterchange(descriptor) {
+  const mapped = mapLessonkitIds(descriptor);
+  const spaLessons = resolveSpaLessons(descriptor);
+  return {
+    format: "lessonkit",
+    version: "1",
+    course: {
+      id: mapped.courseId,
+      title: descriptor.title
+    },
+    lessons: spaLessons.map((l) => ({
+      id: l.id,
+      title: l.title,
+      type: "spa",
+      path: l.path
+    })),
+    tracking: descriptor.tracking
+  };
+}
+
+// src/assessments.ts
+function slugChoiceId(text, index) {
+  const base = text.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "").slice(0, 32);
+  const stem = base.length ? base : "choice";
+  return `${stem}-${index + 1}`;
+}
+function assessmentDescriptorToLxpack(assessment) {
+  const choices = assessment.choices.map((text, index) => {
+    const id = slugChoiceId(text, index);
+    return {
+      id,
+      text,
+      correct: text === assessment.answer
+    };
+  });
+  return {
+    id: assessment.checkId,
+    passingScore: assessment.passingScore ?? 1,
+    questions: [
+      {
+        id: "q1",
+        prompt: assessment.question,
+        choices
+      }
+    ]
+  };
+}
+function extractAssessments(descriptor) {
+  return (descriptor.assessments ?? []).map(assessmentDescriptorToLxpack);
+}
+
+// src/writeProject.ts
+var import_promises = require("fs/promises");
+var import_node_path2 = require("path");
+
+// src/assessmentYaml.ts
+function yamlQuote(value) {
+  return JSON.stringify(value);
+}
+function emitAssessmentYaml(assessment) {
+  const lx = assessmentDescriptorToLxpack(assessment);
+  const lines = [];
+  lines.push(`id: ${lx.id}`);
+  lines.push(`passingScore: ${lx.passingScore}`);
+  lines.push("questions:");
+  for (const question of lx.questions) {
+    lines.push(`  - id: ${question.id}`);
+    lines.push(`    prompt: ${yamlQuote(question.prompt)}`);
+    lines.push("    choices:");
+    for (const choice of question.choices) {
+      lines.push(`      - id: ${choice.id}`);
+      lines.push(`        text: ${yamlQuote(choice.text)}`);
+      if (choice.correct) lines.push("        correct: true");
+    }
+  }
+  return `${lines.join("\n")}
+`;
+}
+
+// src/yaml.ts
+function yamlQuote2(value) {
+  if (/[:#\n\r]/.test(value) || value.startsWith(" ") || value.endsWith(" ")) {
+    return JSON.stringify(value);
+  }
+  return value;
+}
+function emitCourseYaml(opts) {
+  const lines = [];
+  lines.push(`title: ${yamlQuote2(opts.title)}`);
+  lines.push(`version: ${yamlQuote2(opts.version)}`);
+  if (opts.description) lines.push(`description: ${yamlQuote2(opts.description)}`);
+  if (opts.runtime) {
+    lines.push("runtime:");
+    lines.push(`  theme: ${yamlQuote2(opts.runtime.theme)}`);
+    if (opts.runtime.cssVariables && Object.keys(opts.runtime.cssVariables).length) {
+      lines.push("  cssVariables:");
+      for (const [key, value] of Object.entries(opts.runtime.cssVariables).sort(
+        ([a], [b]) => a.localeCompare(b)
+      )) {
+        lines.push(`    ${key}: ${JSON.stringify(String(value))}`);
+      }
+    }
+  }
+  if (opts.tracking?.completion?.threshold !== void 0) {
+    lines.push("tracking:");
+    lines.push("  completion:");
+    lines.push(`    threshold: ${opts.tracking.completion.threshold}`);
+  }
+  lines.push("lessons:");
+  for (const lesson of opts.lessons) {
+    lines.push(`  - id: ${lesson.id}`);
+    lines.push(`    title: ${yamlQuote2(lesson.title)}`);
+    lines.push(`    type: spa`);
+    lines.push(`    path: ${lesson.path}`);
+  }
+  if (opts.assessments.length) {
+    lines.push("assessments:");
+    for (const assessment of opts.assessments) {
+      lines.push(`  - id: ${assessment.id}`);
+      lines.push(`    file: ${assessment.file}`);
+    }
+  }
+  return `${lines.join("\n")}
+`;
+}
+
+// src/writeProject.ts
+async function copyDir(src, dest) {
+  await (0, import_promises.mkdir)((0, import_node_path2.dirname)(dest), { recursive: true });
+  await (0, import_promises.cp)(src, dest, { recursive: true });
+}
+async function writeLxpackProject(options) {
+  const validation = validateDescriptor(options.descriptor);
+  if (!validation.ok) {
+    throw new Error(
+      validation.issues.map((i) => `${i.path}: ${i.message}`).join("; ")
+    );
+  }
+  const descriptor = validation.descriptor;
+  const outDir = (0, import_node_path2.resolve)(options.outDir);
+  await (0, import_promises.mkdir)(outDir, { recursive: true });
+  const spaLessons = resolveSpaLessons(descriptor);
+  const runtime = descriptor.theme ? themeToLxpackRuntime(descriptor.theme) : void 0;
+  const assessments = (descriptor.assessments ?? []).map((a) => ({
+    id: a.checkId,
+    file: `assessments/${a.checkId}.yaml`
+  }));
+  if (descriptor.layout === "single-spa") {
+    const srcDist = (0, import_node_path2.resolve)(options.spaDistDir ?? descriptor.spaDistDir ?? "dist");
+    try {
+      await (0, import_promises.access)(srcDist);
+    } catch {
+      throw new Error(`spaDistDir not found: ${srcDist}`);
+    }
+    const destDist = (0, import_node_path2.join)(outDir, "dist");
+    await (0, import_promises.rm)(destDist, { recursive: true, force: true });
+    await copyDir(srcDist, destDist);
+  } else {
+    const lessonDirs = options.lessonSpaDirs ?? {};
+    for (const lesson of descriptor.lessons) {
+      const src = lessonDirs[lesson.id];
+      if (!src) {
+        throw new Error(`lessonSpaDirs missing build output for lesson "${lesson.id}"`);
+      }
+      const dest = (0, import_node_path2.join)(outDir, lesson.spaPath);
+      assertResolvedPathUnderRoot(outDir, dest);
+      await (0, import_promises.rm)(dest, { recursive: true, force: true });
+      await copyDir((0, import_node_path2.resolve)(src), dest);
+    }
+  }
+  if (assessments.length) {
+    const assessmentsDir = (0, import_node_path2.join)(outDir, "assessments");
+    await (0, import_promises.mkdir)(assessmentsDir, { recursive: true });
+    for (const assessment of descriptor.assessments ?? []) {
+      await (0, import_promises.writeFile)(
+        (0, import_node_path2.join)(outDir, `assessments/${assessment.checkId}.yaml`),
+        emitAssessmentYaml(assessment),
+        "utf-8"
+      );
+    }
+  }
+  const courseYamlPath = (0, import_node_path2.join)(outDir, "course.yaml");
+  await (0, import_promises.writeFile)(
+    courseYamlPath,
+    emitCourseYaml({
+      title: descriptor.title,
+      version: descriptor.version ?? "1.0.0",
+      runtime,
+      tracking: descriptor.tracking,
+      lessons: spaLessons.map((l) => ({
+        id: l.id,
+        title: l.title,
+        type: "spa",
+        path: l.path
+      })),
+      assessments
+    }),
+    "utf-8"
+  );
+  const lessonkitJsonPath = (0, import_node_path2.join)(outDir, "lessonkit.json");
+  await (0, import_promises.writeFile)(
+    lessonkitJsonPath,
+    `${JSON.stringify(descriptorToInterchange(descriptor), null, 2)}
+`,
+    "utf-8"
+  );
+  return { outDir, courseYamlPath, lessonkitJsonPath };
+}
+
+// src/packageCourse.ts
+var import_promises2 = require("fs/promises");
+var import_node_path3 = 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_path3.resolve)(options.courseDir),
+    target: options.target
+  });
+}
+async function buildLessonkitProject(options) {
+  return (0, import_api.buildCourse)({
+    courseDir: (0, import_node_path3.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 outDir = (0, import_node_path3.resolve)(writeOpts.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;
+  const stagingDir = await (0, import_promises2.mkdtemp)((0, import_node_path3.join)((0, import_node_os.tmpdir)(), "lessonkit-lxpack-"));
+  let promoted = false;
+  try {
+    const written = await writeLxpackProject({ ...writeOpts, descriptor, outDir: stagingDir });
+    const courseDir = written.outDir;
+    const assessments = extractAssessments(descriptor);
+    const validation = await validateLessonkitProject({ courseDir, target });
+    if (!validation.ok) {
+      return {
+        ok: false,
+        courseDir: outDir,
+        target,
+        validation,
+        issues: validation.issues.map((i) => ({
+          path: i.path,
+          message: i.message,
+          severity: i.severity
+        }))
+      };
+    }
+    const outputBase = outputBaseDir ?? ".lxpack/out";
+    await (0, import_promises2.mkdir)((0, import_node_path3.join)(courseDir, outputBase), { recursive: true });
+    const defaultOutput = output ?? (dir ? (0, import_node_path3.join)(outputBase, target) : (0, import_node_path3.join)(outputBase, `course-${target}.zip`));
+    const build = await buildLessonkitProject({
+      courseDir,
+      target,
+      output: defaultOutput.startsWith("/") ? defaultOutput : (0, import_node_path3.join)(courseDir, defaultOutput),
+      dir,
+      assessments: assessments.length ? assessments : void 0
+    });
+    if (!build.ok) {
+      return {
+        ok: false,
+        courseDir: outDir,
+        target,
+        validation,
+        build,
+        issues: build.issues.map((i) => ({
+          path: i.path,
+          message: i.message,
+          severity: i.severity
+        }))
+      };
+    }
+    await (0, import_promises2.rm)(outDir, { recursive: true, force: true });
+    await (0, import_promises2.mkdir)((0, import_node_path3.dirname)(outDir), { recursive: true });
+    await (0, import_promises2.rename)(stagingDir, outDir);
+    promoted = true;
+    const remapArtifactPath = (artifactPath) => {
+      if (!artifactPath) return void 0;
+      const resolved = (0, import_node_path3.resolve)(artifactPath);
+      const stagingResolved = (0, import_node_path3.resolve)(stagingDir);
+      if (resolved === stagingResolved || resolved.startsWith(stagingResolved + "/")) {
+        return (0, import_node_path3.join)(outDir, resolved.slice(stagingResolved.length + 1));
+      }
+      return artifactPath;
+    };
+    return {
+      ok: true,
+      courseDir: outDir,
+      target,
+      outputPath: remapArtifactPath("outputPath" in build ? build.outputPath : void 0),
+      outputDir: remapArtifactPath("outputDir" in build ? build.outputDir : void 0),
+      fileCount: build.fileCount,
+      validation,
+      build
+    };
+  } finally {
+    if (!promoted) {
+      await (0, import_promises2.rm)(stagingDir, { recursive: true, force: true }).catch(() => void 0);
+    }
+  }
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  assessmentDescriptorToLxpack,
+  buildLessonkitProject,
+  descriptorToInterchange,
+  extractAssessments,
+  mapLessonkitIds,
+  packageLessonkitCourse,
+  resolveSpaLessons,
+  themeToLxpackRuntime,
+  validateDescriptor,
+  validateLessonkitProject,
+  writeLxpackProject
+});