@lxpack/scorm 0.1.0 → 0.1.1

package/README.md

@@ -0,0 +1,137 @@
+# @lxpack/scorm
+
+[![npm version](https://img.shields.io/npm/v/@lxpack/scorm)](https://www.npmjs.com/package/@lxpack/scorm)
+[![CI](https://github.com/eddiethedean/lxpack/actions/workflows/ci.yml/badge.svg)](https://github.com/eddiethedean/lxpack/actions/workflows/ci.yml)
+[![License](https://img.shields.io/github/license/eddiethedean/lxpack)](https://github.com/eddiethedean/lxpack/blob/main/LICENSE)
+[![Node.js](https://img.shields.io/badge/node-%3E%3D20-brightgreen)](https://nodejs.org/)
+
+SCORM 1.2 and standalone HTML export for LXPack courses.
+
+Part of [LXPack](https://github.com/eddiethedean/lxpack) — an AI-native learning experience compiler and runtime.
+
+| Related | Package |
+|---------|---------|
+| CLI | [`@lxpack/cli`](../cli/README.md) |
+| Manifest validation | [`@lxpack/validators`](../validators/README.md) |
+| Embedded client | [`@lxpack/runtime`](../runtime/README.md) |
+
+## Install
+
+```bash
+npm install @lxpack/scorm
+```
+
+Requires Node.js 20+.
+
+## Usage
+
+```ts
+import { readFile } from "node:fs/promises";
+import type { CourseManifest } from "@lxpack/validators";
+import { buildRuntimeAssessmentBundle } from "@lxpack/validators";
+import {
+  packageCourse,
+  packageStandaloneDir,
+  buildIndexHtml,
+  collectFiles,
+  safeJsonForHtml,
+  courseSlug,
+} from "@lxpack/scorm";
+
+const courseDir = "/path/to/my-course";
+const manifest: CourseManifest = /* from validateCourse */;
+const assessmentBundle = await buildRuntimeAssessmentBundle(courseDir, manifest);
+
+const runtimeClientJs = await readFile("path/to/client.js", "utf8");
+const runtimeCss = await readFile("path/to/styles.css", "utf8");
+
+await packageCourse({
+  courseDir,
+  manifest,
+  target: "scorm12",
+  outputPath: "/path/to/output/course-scorm12.zip",
+  runtimeClientJs,
+  runtimeCss,
+  assessmentBundle,
+});
+```
+
+### Standalone directory
+
+```ts
+await packageStandaloneDir({
+  courseDir,
+  manifest,
+  target: "standalone",
+  outputDir: "/path/to/output/standalone",
+  runtimeClientJs,
+  runtimeCss,
+  assessmentBundle,
+});
+```
+
+Most users should use `lxpack build` from [`@lxpack/cli`](../cli/README.md) instead of calling these APIs directly.
+
+## Exports
+
+| Export | Description |
+|--------|-------------|
+| `packageCourse(options)` | Build a SCORM 1.2 or standalone ZIP |
+| `packageStandaloneDir(options)` | Write an unpacked directory (ZIP or SCORM layout) |
+| `generateImsManifest(manifest, files)` | SCORM 1.2 `imsmanifest.xml` |
+| `buildIndexHtml(options)` | Course shell HTML with embedded config |
+| `buildRuntimeConfig(options)` | Config object passed to `safeJsonForHtml` |
+| `collectFiles(courseDir, baseDir)` | Course assets for packaging (respects skip rules) |
+| `shouldSkipCourseFile(rel)` | Whether a relative path is omitted from exports |
+| `buildManifestFileList(courseFiles)` | File list for `imsmanifest.xml` |
+| `safeJsonForHtml(value)` | JSON safe for `<script type="application/json">` blocks |
+| `courseSlug(manifest)` | Stable slug for ZIP names and manifest identifiers |
+| `ExportTarget` | `"scorm12"` \| `"standalone"` |
+
+### `PackageOptions`
+
+| Field | Description |
+|-------|-------------|
+| `courseDir` | Course root directory |
+| `manifest` | Parsed `course.yaml` |
+| `outputPath` | Destination ZIP path (`packageCourse`) |
+| `target` | `scorm12` or `standalone` |
+| `runtimeClientJs` | Contents of `@lxpack/runtime/client` bundle |
+| `runtimeCss` | Runtime stylesheet |
+| `assessmentBundle` | Optional; from `buildRuntimeAssessmentBundle()` |
+
+## What gets packaged
+
+**Included**
+
+- Lessons, interactions, and assets referenced by the manifest
+- `index.html` — shell with embedded manifest + assessment config
+- `lxpack-runtime.js` — browser client bundle
+- `imsmanifest.xml` — SCORM 1.2 target only
+
+**Excluded** (`shouldSkipCourseFile`)
+
+- `course.yaml`, `lxpack.config.json`, `.lxpack/`
+- `assessments/**` — author YAML; assessments are embedded in config instead
+- Root `index.html` if present (packager generates the entry page)
+
+Answer keys are only present inside the JSON config block (with `<` escaped via `safeJsonForHtml`), not as downloadable files.
+
+## Development
+
+From the monorepo root:
+
+```bash
+pnpm --filter @lxpack/scorm build
+pnpm --filter @lxpack/scorm test
+pnpm --filter @lxpack/scorm typecheck
+```
+
+## Links
+
+- [LXPack repository](https://github.com/eddiethedean/lxpack)
+- [Changelog](https://github.com/eddiethedean/lxpack/blob/main/CHANGELOG.md)
+
+## License
+
+Apache-2.0

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { CourseManifest } from '@lxpack/validators';
+import { CourseManifest, RuntimeAssessmentBundle } from '@lxpack/validators';
 
 declare function manifestIdentifier(manifest: CourseManifest): string;
 declare function generateImsManifest(manifest: CourseManifest, files: string[], launchUrl?: string): string;
@@ -7,7 +7,15 @@ interface BuildHtmlOptions {
     manifest: CourseManifest;
     runtimeCss: string;
     mode: "standalone" | "scorm12";
+    assessmentBundle?: RuntimeAssessmentBundle;
 }
+declare function buildRuntimeConfig(options: BuildHtmlOptions): {
+    manifest: CourseManifest;
+    baseUrl: string;
+    mode: BuildHtmlOptions["mode"];
+    assessments?: RuntimeAssessmentBundle["assessments"];
+    answerKeys?: RuntimeAssessmentBundle["answerKeys"];
+};
 declare function buildIndexHtml(options: BuildHtmlOptions): string;
 
 type ExportTarget = "scorm12" | "standalone";
@@ -18,7 +26,9 @@ interface PackageOptions {
     target: ExportTarget;
     runtimeClientJs: string;
     runtimeCss: string;
+    assessmentBundle?: RuntimeAssessmentBundle;
 }
+declare function shouldSkipCourseFile(rel: string): boolean;
 declare function collectFiles(dir: string, baseDir: string): Promise<Array<{
     path: string;
     fullPath: string;
@@ -37,4 +47,10 @@ declare function packageStandaloneDir(options: Omit<PackageOptions, "outputPath"
     fileCount: number;
 }>;
 
-export { type BuildHtmlOptions, type ExportTarget, type PackageOptions, buildIndexHtml, buildManifestFileList, collectFiles, generateImsManifest, manifestIdentifier, packageCourse, packageStandaloneDir };
+/** JSON safe to embed in HTML script blocks (prevents `</script>` breakout). */
+declare function safeJsonForHtml(value: unknown): string;
+
+/** Stable slug for ZIP filenames and SCORM identifiers. */
+declare function courseSlug(manifest: CourseManifest): string;
+
+export { type BuildHtmlOptions, type ExportTarget, type PackageOptions, buildIndexHtml, buildManifestFileList, buildRuntimeConfig, collectFiles, courseSlug, generateImsManifest, manifestIdentifier, packageCourse, packageStandaloneDir, safeJsonForHtml, shouldSkipCourseFile };

package/dist/index.js

@@ -1,13 +1,19 @@
-// src/manifest.ts
-function manifestIdentifier(manifest) {
+// src/slug.ts
+function courseSlug(manifest) {
   const slug = manifest.title.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "");
   if (slug) return slug;
   let hash = 0;
-  for (let i = 0; i < manifest.title.length; i++) {
-    hash = (hash << 5) - hash + manifest.title.charCodeAt(i);
+  const key = `${manifest.title}::${manifest.version}`;
+  for (let i = 0; i < key.length; i++) {
+    hash = (hash << 5) - hash + key.charCodeAt(i);
     hash |= 0;
   }
-  return `course-${Math.abs(hash)}`;
+  return `course-${Math.abs(hash).toString(36)}`;
+}
+
+// src/manifest.ts
+function manifestIdentifier(manifest) {
+  return courseSlug(manifest);
 }
 function generateImsManifest(manifest, files, launchUrl = "index.html") {
   const identifier = manifestIdentifier(manifest);
@@ -46,14 +52,27 @@ function escapeXml(text) {
   return text.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;").replace(/'/g, "&apos;");
 }
 
+// src/safe-json.ts
+function safeJsonForHtml(value) {
+  return JSON.stringify(value).replace(/</g, "\\u003c");
+}
+
 // src/build-html.ts
-function buildIndexHtml(options) {
-  const { manifest, runtimeCss, mode } = options;
-  const config = JSON.stringify({
+function buildRuntimeConfig(options) {
+  const { manifest, mode, assessmentBundle } = options;
+  return {
     manifest,
     baseUrl: ".",
-    mode
-  });
+    mode,
+    ...assessmentBundle ? {
+      assessments: assessmentBundle.assessments,
+      answerKeys: assessmentBundle.answerKeys
+    } : {}
+  };
+}
+function buildIndexHtml(options) {
+  const { manifest, runtimeCss } = options;
+  const config = safeJsonForHtml(buildRuntimeConfig(options));
   return `<!DOCTYPE html>
 <html lang="en">
 <head>
@@ -77,7 +96,8 @@ function escapeHtml(text) {
 }
 
 // src/package.ts
-import { readFile, readdir } from "fs/promises";
+import { readFile, readdir, writeFile, mkdir, cp } from "fs/promises";
+import { existsSync } from "fs";
 import { dirname, join, relative } from "path";
 import JSZip from "jszip";
 var SKIP_FILES = /* @__PURE__ */ new Set([
@@ -85,6 +105,18 @@ var SKIP_FILES = /* @__PURE__ */ new Set([
   "lxpack.config.ts",
   "lxpack.config.json"
 ]);
+function shouldSkipCourseFile(rel) {
+  if (SKIP_FILES.has(rel) || rel.startsWith(".lxpack")) {
+    return true;
+  }
+  if (rel === "index.html") {
+    return true;
+  }
+  if (rel.startsWith("assessments/")) {
+    return true;
+  }
+  return false;
+}
 async function collectFiles(dir, baseDir) {
   const entries = await readdir(dir, { withFileTypes: true });
   const files = [];
@@ -97,10 +129,7 @@ async function collectFiles(dir, baseDir) {
       files.push(...await collectFiles(fullPath, baseDir));
     } else if (entry.isFile()) {
       const rel = relative(baseDir, fullPath).replace(/\\/g, "/");
-      if (SKIP_FILES.has(rel) || rel.startsWith(".lxpack")) {
-        continue;
-      }
-      if (rel === "index.html") {
+      if (shouldSkipCourseFile(rel)) {
         continue;
       }
       files.push({ path: rel, fullPath });
@@ -112,7 +141,15 @@ function buildManifestFileList(courseFiles) {
   return ["index.html", "lxpack-runtime.js", ...courseFiles.map((f) => f.path)];
 }
 async function packageCourse(options) {
-  const { courseDir, manifest, outputPath, target, runtimeClientJs, runtimeCss } = options;
+  const {
+    courseDir,
+    manifest,
+    outputPath,
+    target,
+    runtimeClientJs,
+    runtimeCss,
+    assessmentBundle
+  } = options;
   const zip = new JSZip();
   const mode = target === "scorm12" ? "scorm12" : "standalone";
   const courseFiles = await collectFiles(courseDir, courseDir);
@@ -120,7 +157,12 @@ async function packageCourse(options) {
     const content = await readFile(file.fullPath);
     zip.file(file.path, content);
   }
-  const indexHtml = buildIndexHtml({ manifest, runtimeCss, mode });
+  const indexHtml = buildIndexHtml({
+    manifest,
+    runtimeCss,
+    mode,
+    assessmentBundle
+  });
   zip.file("index.html", indexHtml);
   zip.file("lxpack-runtime.js", runtimeClientJs);
   if (target === "scorm12") {
@@ -134,7 +176,6 @@ async function packageCourse(options) {
     type: "nodebuffer",
     compression: "DEFLATE"
   });
-  const { writeFile } = await import("fs/promises");
   await writeFile(outputPath, buffer);
   return {
     outputPath,
@@ -142,9 +183,15 @@ async function packageCourse(options) {
   };
 }
 async function packageStandaloneDir(options) {
-  const { courseDir, manifest, outputDir, target, runtimeClientJs, runtimeCss } = options;
-  const { mkdir, writeFile, cp } = await import("fs/promises");
-  const { existsSync } = await import("fs");
+  const {
+    courseDir,
+    manifest,
+    outputDir,
+    target,
+    runtimeClientJs,
+    runtimeCss,
+    assessmentBundle
+  } = options;
   await mkdir(outputDir, { recursive: true });
   const mode = target === "scorm12" ? "scorm12" : "standalone";
   const courseFiles = await collectFiles(courseDir, courseDir);
@@ -158,7 +205,12 @@ async function packageStandaloneDir(options) {
     await cp(file.fullPath, dest);
     fileCount++;
   }
-  const indexHtml = buildIndexHtml({ manifest, runtimeCss, mode });
+  const indexHtml = buildIndexHtml({
+    manifest,
+    runtimeCss,
+    mode,
+    assessmentBundle
+  });
   await writeFile(join(outputDir, "index.html"), indexHtml);
   await writeFile(join(outputDir, "lxpack-runtime.js"), runtimeClientJs);
   fileCount += 2;
@@ -175,9 +227,13 @@ async function packageStandaloneDir(options) {
 export {
   buildIndexHtml,
   buildManifestFileList,
+  buildRuntimeConfig,
   collectFiles,
+  courseSlug,
   generateImsManifest,
   manifestIdentifier,
   packageCourse,
-  packageStandaloneDir
+  packageStandaloneDir,
+  safeJsonForHtml,
+  shouldSkipCourseFile
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lxpack/scorm",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "SCORM and standalone HTML export for LXPack",
   "license": "Apache-2.0",
   "repository": {
@@ -39,7 +39,7 @@
   ],
   "dependencies": {
     "jszip": "^3.10.1",
-    "@lxpack/validators": "0.1.0"
+    "@lxpack/validators": "0.1.1"
   },
   "devDependencies": {
     "@types/node": "^22.13.10",