@lessonkit/lxpack 0.6.0

package/dist/index.js

@@ -0,0 +1,543 @@
+// src/validateDescriptor.ts
+import { validateId } from "@lessonkit/core";
+
+// src/spaPath.ts
+import { resolve, sep } from "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 = resolve(root);
+  const targetResolved = resolve(target);
+  const prefix = rootResolved.endsWith(sep) ? rootResolved : rootResolved + sep;
+  if (targetResolved !== rootResolved && !targetResolved.startsWith(prefix)) {
+    throw new Error(`unsafe path escapes project root: ${target}`);
+  }
+}
+
+// src/validateDescriptor.ts
+function normalizeDescriptor(input) {
+  const course = 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 = 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 = 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 = 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 = 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 = 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 = 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
+import { assertValidId } from "@lessonkit/core";
+function mapLessonkitIds(descriptor) {
+  const courseId = assertValidId(descriptor.courseId, "courseId");
+  const lessonIds = descriptor.lessons.map((l) => assertValidId(l.id, "lessonId"));
+  const checkIds = (descriptor.assessments ?? []).map(
+    (a) => assertValidId(a.checkId, "checkId")
+  );
+  return { courseId, lessonIds, checkIds };
+}
+
+// src/theme.ts
+import { getPresetTheme, themeToCssVariables } from "@lessonkit/themes";
+function themeToLxpackRuntime(input) {
+  const theme = input.theme ?? getPresetTheme(input.preset ?? "default");
+  const raw = 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
+import { access, cp, mkdir, rm, writeFile } from "fs/promises";
+import { dirname, join, resolve as resolve2 } from "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 mkdir(dirname(dest), { recursive: true });
+  await 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 = resolve2(options.outDir);
+  await 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 = resolve2(options.spaDistDir ?? descriptor.spaDistDir ?? "dist");
+    try {
+      await access(srcDist);
+    } catch {
+      throw new Error(`spaDistDir not found: ${srcDist}`);
+    }
+    const destDist = join(outDir, "dist");
+    await 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 = join(outDir, lesson.spaPath);
+      assertResolvedPathUnderRoot(outDir, dest);
+      await rm(dest, { recursive: true, force: true });
+      await copyDir(resolve2(src), dest);
+    }
+  }
+  if (assessments.length) {
+    const assessmentsDir = join(outDir, "assessments");
+    await mkdir(assessmentsDir, { recursive: true });
+    for (const assessment of descriptor.assessments ?? []) {
+      await writeFile(
+        join(outDir, `assessments/${assessment.checkId}.yaml`),
+        emitAssessmentYaml(assessment),
+        "utf-8"
+      );
+    }
+  }
+  const courseYamlPath = join(outDir, "course.yaml");
+  await 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 = join(outDir, "lessonkit.json");
+  await writeFile(
+    lessonkitJsonPath,
+    `${JSON.stringify(descriptorToInterchange(descriptor), null, 2)}
+`,
+    "utf-8"
+  );
+  return { outDir, courseYamlPath, lessonkitJsonPath };
+}
+
+// src/packageCourse.ts
+import { mkdir as mkdir2, mkdtemp, rename, rm as rm2 } from "fs/promises";
+import { dirname as dirname2, join as join2, resolve as resolve3 } from "path";
+import { tmpdir } from "os";
+import {
+  buildCourse,
+  validateCourse
+} from "@lxpack/api";
+async function validateLessonkitProject(options) {
+  return validateCourse({
+    courseDir: resolve3(options.courseDir),
+    target: options.target
+  });
+}
+async function buildLessonkitProject(options) {
+  return buildCourse({
+    courseDir: resolve3(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 = resolve3(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 mkdtemp(join2(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 mkdir2(join2(courseDir, outputBase), { recursive: true });
+    const defaultOutput = output ?? (dir ? join2(outputBase, target) : join2(outputBase, `course-${target}.zip`));
+    const build = await buildLessonkitProject({
+      courseDir,
+      target,
+      output: defaultOutput.startsWith("/") ? defaultOutput : join2(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 rm2(outDir, { recursive: true, force: true });
+    await mkdir2(dirname2(outDir), { recursive: true });
+    await rename(stagingDir, outDir);
+    promoted = true;
+    const remapArtifactPath = (artifactPath) => {
+      if (!artifactPath) return void 0;
+      const resolved = resolve3(artifactPath);
+      const stagingResolved = resolve3(stagingDir);
+      if (resolved === stagingResolved || resolved.startsWith(stagingResolved + "/")) {
+        return join2(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 rm2(stagingDir, { recursive: true, force: true }).catch(() => void 0);
+    }
+  }
+}
+export {
+  assessmentDescriptorToLxpack,
+  buildLessonkitProject,
+  descriptorToInterchange,
+  extractAssessments,
+  mapLessonkitIds,
+  packageLessonkitCourse,
+  resolveSpaLessons,
+  themeToLxpackRuntime,
+  validateDescriptor,
+  validateLessonkitProject,
+  writeLxpackProject
+};

package/package.json

@@ -0,0 +1,66 @@
+{
+  "name": "@lessonkit/lxpack",
+  "version": "0.6.0",
+  "private": false,
+  "description": "LXPack export adapter for LessonKit courses (SCORM, standalone, xAPI, cmi5).",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/eddiethedean/lessonkit.git",
+    "directory": "packages/lxpack"
+  },
+  "homepage": "https://github.com/eddiethedean/lessonkit",
+  "bugs": {
+    "url": "https://github.com/eddiethedean/lessonkit/issues"
+  },
+  "keywords": [
+    "lessonkit",
+    "lxpack",
+    "scorm",
+    "lms",
+    "packaging",
+    "elearning"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    },
+    "./bridge": {
+      "types": "./dist/bridge.d.ts",
+      "import": "./dist/bridge.js",
+      "require": "./dist/bridge.cjs"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsup src/index.ts src/bridge.ts --format esm,cjs --dts",
+    "dev": "tsup src/index.ts src/bridge.ts --format esm,cjs --dts --watch",
+    "prepublishOnly": "npm run build",
+    "typecheck": "tsc -p tsconfig.json",
+    "test": "vitest run --passWithNoTests",
+    "test:coverage": "vitest run --coverage --passWithNoTests=false",
+    "lint": "echo \"(no lint configured yet)\""
+  },
+  "dependencies": {
+    "@lessonkit/core": "0.6.0",
+    "@lessonkit/themes": "0.6.0",
+    "@lxpack/api": "^0.4.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.13.10",
+    "tsup": "^8.5.0",
+    "typescript": "^5.8.3",
+    "vitest": "^3.2.4"
+  }
+}