@lxpack/cli 0.2.2 → 0.3.0

package/README.md

@@ -7,7 +7,7 @@
 
 Command-line tool for scaffolding, previewing, validating, and packaging LXPack courses.
 
-Part of [LXPack](https://github.com/eddiethedean/lxpack) — an AI-native learning experience compiler and runtime (**v0.2.2**).
+Part of [LXPack](https://github.com/eddiethedean/lxpack) — an AI-native learning experience compiler and runtime (**v0.3.0**).
 
 | Related | Package |
 |---------|---------|
@@ -34,6 +34,8 @@ lxpack preview          # http://127.0.0.1:3847 by default
 lxpack validate
 lxpack build --target scorm12
 lxpack build --target scorm2004
+lxpack build --target xapi
+lxpack build --target cmi5
 ```
 
 Output lands in `.lxpack/` unless overridden by `-o` or `lxpack.config.json`.
@@ -44,14 +46,14 @@ Output lands in `.lxpack/` unless overridden by `-o` or `lxpack.config.json`.
 |---------|-------------|
 | `init <name>` | Scaffold a new course (`-d, --dir <path>`, `-f, --force`) |
 | `preview` | Start local preview server (`-p, --port`, `-H, --host`) |
-| `validate` | Validate `course.yaml` and referenced files |
+| `validate` | Validate `course.yaml` and referenced files (`-t, --target` for export checks) |
 | `build` | Package for LMS or standalone export |
 
 ### `build` options
 
 | Option | Description |
 |--------|-------------|
-| `-t, --target <target>` | `scorm12` (default), `scorm2004`, or `standalone` |
+| `-t, --target <target>` | `scorm12` (default), `scorm2004`, `standalone`, `xapi`, or `cmi5` |
 | `-o, --output <path>` | Output ZIP file or directory |
 | `--dir` | Write an unpacked directory instead of a ZIP |
 
@@ -59,7 +61,19 @@ Output lands in `.lxpack/` unless overridden by `-o` or `lxpack.config.json`.
 
 **SCORM 2004** builds produce a multi-SCO ZIP: one launch page per activity under `sco/<activityId>/index.html`, plus shared `lxpack-runtime.js` and `lxpack-components.js`.
 
-**Preview** serves the runtime client, optional components bundle at `/runtime/components.js`, and installs SCORM API simulators (1.2 and 2004) for local testing. Direct HTTP access to `assessments/*.yaml` under `/course/` returns 404; quiz content is embedded in the preview page config only.
+**Preview** serves the runtime client and optional components bundle at `/runtime/components.js`. Configure SCORM simulators in `lxpack.config.json`:
+
+```json
+{ "preview": { "scormMode": "local" } }
+```
+
+| `scormMode` | Behavior |
+|-------------|----------|
+| `local` | `localStorage` progress (default) |
+| `scorm12` | SCORM 1.2 simulator on `window.API` |
+| `scorm2004` | SCORM 2004 simulator on `window.API_1484_11` |
+
+Direct HTTP access to `assessments/`, `course.yaml`, `lxpack.config.json`, and `.lxpack/` under `/course/` returns 404; quiz content is embedded in the preview page config only.
 
 ### Course discovery
 

package/dist/cli.d.ts

@@ -3,11 +3,40 @@ import { z } from 'zod';
 
 declare const lxpackConfigSchema: z.ZodObject<{
     exports: z.ZodOptional<z.ZodObject<{
-        defaultTarget: z.ZodOptional<z.ZodEnum<["scorm12", "scorm2004", "standalone"]>>;
+        defaultTarget: z.ZodOptional<z.ZodEnum<["scorm12", "scorm2004", "standalone", "xapi", "cmi5"]>>;
     }, "strip", z.ZodTypeAny, {
-        defaultTarget?: "scorm12" | "scorm2004" | "standalone" | undefined;
+        defaultTarget?: "scorm12" | "scorm2004" | "standalone" | "xapi" | "cmi5" | undefined;
     }, {
-        defaultTarget?: "scorm12" | "scorm2004" | "standalone" | undefined;
+        defaultTarget?: "scorm12" | "scorm2004" | "standalone" | "xapi" | "cmi5" | undefined;
+    }>>;
+    preview: z.ZodOptional<z.ZodObject<{
+        scormMode: z.ZodOptional<z.ZodEnum<["local", "scorm12", "scorm2004"]>>;
+    }, "strict", z.ZodTypeAny, {
+        scormMode?: "scorm12" | "scorm2004" | "local" | undefined;
+    }, {
+        scormMode?: "scorm12" | "scorm2004" | "local" | undefined;
+    }>>;
+    xapi: z.ZodOptional<z.ZodObject<{
+        preview: z.ZodOptional<z.ZodObject<{
+            logStatements: z.ZodOptional<z.ZodBoolean>;
+            mockLrs: z.ZodOptional<z.ZodBoolean>;
+        }, "strict", z.ZodTypeAny, {
+            logStatements?: boolean | undefined;
+            mockLrs?: boolean | undefined;
+        }, {
+            logStatements?: boolean | undefined;
+            mockLrs?: boolean | undefined;
+        }>>;
+    }, "strict", z.ZodTypeAny, {
+        preview?: {
+            logStatements?: boolean | undefined;
+            mockLrs?: boolean | undefined;
+        } | undefined;
+    }, {
+        preview?: {
+            logStatements?: boolean | undefined;
+            mockLrs?: boolean | undefined;
+        } | undefined;
     }>>;
     output: z.ZodOptional<z.ZodObject<{
         dir: z.ZodOptional<z.ZodString>;
@@ -17,15 +46,33 @@ declare const lxpackConfigSchema: z.ZodObject<{
         dir?: string | undefined;
     }>>;
 }, "strict", z.ZodTypeAny, {
+    preview?: {
+        scormMode?: "scorm12" | "scorm2004" | "local" | undefined;
+    } | undefined;
+    xapi?: {
+        preview?: {
+            logStatements?: boolean | undefined;
+            mockLrs?: boolean | undefined;
+        } | undefined;
+    } | undefined;
     exports?: {
-        defaultTarget?: "scorm12" | "scorm2004" | "standalone" | undefined;
+        defaultTarget?: "scorm12" | "scorm2004" | "standalone" | "xapi" | "cmi5" | undefined;
     } | undefined;
     output?: {
         dir?: string | undefined;
     } | undefined;
 }, {
+    preview?: {
+        scormMode?: "scorm12" | "scorm2004" | "local" | undefined;
+    } | undefined;
+    xapi?: {
+        preview?: {
+            logStatements?: boolean | undefined;
+            mockLrs?: boolean | undefined;
+        } | undefined;
+    } | undefined;
     exports?: {
-        defaultTarget?: "scorm12" | "scorm2004" | "standalone" | undefined;
+        defaultTarget?: "scorm12" | "scorm2004" | "standalone" | "xapi" | "cmi5" | undefined;
     } | undefined;
     output?: {
         dir?: string | undefined;

package/dist/cli.js

@@ -85,8 +85,17 @@ import { z } from "zod";
 import { formatErrorMessage, isPathContained } from "@lxpack/validators";
 var lxpackConfigSchema = z.object({
   exports: z.object({
-    defaultTarget: z.enum(["scorm12", "scorm2004", "standalone"]).optional()
+    defaultTarget: z.enum(["scorm12", "scorm2004", "standalone", "xapi", "cmi5"]).optional()
   }).optional(),
+  preview: z.object({
+    scormMode: z.enum(["local", "scorm12", "scorm2004"]).optional()
+  }).strict().optional(),
+  xapi: z.object({
+    preview: z.object({
+      logStatements: z.boolean().optional(),
+      mockLrs: z.boolean().optional()
+    }).strict().optional()
+  }).strict().optional(),
   output: z.object({
     dir: z.string().optional()
   }).optional()
@@ -178,7 +187,7 @@ assessments:
   - id: final_quiz
     file: assessments/final.yaml
 
-# Optional Phase 2 features (see examples/branching-demo):
+# Optional branching (see examples/branching-demo):
 # variables:
 #   path:
 #     default: intro
@@ -188,6 +197,12 @@ assessments:
 #       variable:
 #         eq: [path, advanced]
 #     goto: component_lesson
+
+# Optional xAPI/cmi5 export (see examples/xapi-awareness):
+# tracking:
+#   xapi:
+#     activityIri: "https://example.test/courses/my-course"
+#     displayName: My Course
 `;
 var WELCOME_MD = `# Welcome
 
@@ -274,6 +289,9 @@ var LXPACK_CONFIG = `{
   "exports": {
     "defaultTarget": "scorm12"
   },
+  "preview": {
+    "scormMode": "local"
+  },
   "output": {
     "dir": ".lxpack"
   }
@@ -361,14 +379,44 @@ function printValidationIssues(validation) {
 
 // src/commands/preview.ts
 import { buildLearnerPageHtml, safeJsonForHtml } from "@lxpack/scorm";
+import { getCourseActivityIri } from "@lxpack/validators";
+
+// src/lib/preview-paths.ts
+function isPreviewBlockedCoursePath(urlPath) {
+  const path = urlPath.split("?")[0] ?? "";
+  if (!path.startsWith("/course/")) {
+    return false;
+  }
+  const rel = path.slice("/course/".length);
+  if (rel.startsWith("assessments/")) {
+    return true;
+  }
+  if (rel === "course.yaml" || rel === "lxpack.config.json") {
+    return true;
+  }
+  if (rel.startsWith(".lxpack/") || rel === ".lxpack") {
+    return true;
+  }
+  return false;
+}
+
+// src/commands/preview.ts
 async function loadPreviewStyles(assetsDir = getRuntimeAssetsDir()) {
   return loadRuntimeStyles(assetsDir);
 }
-function buildPreviewConfig(manifest, assessmentBundle) {
+function buildPreviewConfig(manifest, assessmentBundle, options) {
   return safeJsonForHtml({
     manifest,
     baseUrl: "/course",
     mode: "preview",
+    ...options?.previewScormMode && options.previewScormMode !== "local" ? { previewScormMode: options.previewScormMode } : {},
+    ...options?.activityIri ? { activityIri: options.activityIri } : {},
+    ...options?.xapiPreview ? {
+      xapi: {
+        previewLog: options.xapiPreview.logStatements ?? true,
+        mockLrs: options.xapiPreview.mockLrs ?? true
+      }
+    } : {},
     ...assessmentBundle ? {
       assessments: assessmentBundle.assessments,
       answerKeys: assessmentBundle.answerKeys,
@@ -382,7 +430,7 @@ async function createPreviewServer(courseDir, manifest, assessmentBundle) {
   const app = Fastify({ logger: false });
   app.addHook("onRequest", async (request, reply) => {
     const path = request.url.split("?")[0] ?? "";
-    if (path.startsWith("/course/assessments/")) {
+    if (isPreviewBlockedCoursePath(path)) {
       return reply.code(404).send("Not found");
     }
   });
@@ -397,7 +445,14 @@ async function createPreviewServer(courseDir, manifest, assessmentBundle) {
     decorateReply: false
   });
   const stylesCss = await loadPreviewStyles(runtimeDir);
-  const config = buildPreviewConfig(manifest, assessmentBundle);
+  const lxpackConfig = await loadLxpackConfig(courseDir);
+  const activityIri = getCourseActivityIri(manifest);
+  const previewScormMode = lxpackConfig?.preview?.scormMode ?? "local";
+  const config = buildPreviewConfig(manifest, assessmentBundle, {
+    activityIri,
+    previewScormMode,
+    xapiPreview: lxpackConfig?.xapi?.preview
+  });
   const componentsJs = await readComponentsBundle();
   if (componentsJs) {
     app.get("/runtime/components.js", async (_req, reply) => {
@@ -484,11 +539,42 @@ function logPreviewStarted(host, port) {
 }
 
 // src/commands/validate.ts
-import { validateCourse as validateCourse3 } from "@lxpack/validators";
+import {
+  validateCourse as validateCourse3,
+  validateXapiTracking
+} from "@lxpack/validators";
 import pc3 from "picocolors";
-async function validateCommand() {
+
+// src/lib/targets.ts
+var VALID_EXPORT_TARGETS = [
+  "scorm12",
+  "scorm2004",
+  "standalone",
+  "xapi",
+  "cmi5"
+];
+function isValidExportTarget(target) {
+  return VALID_EXPORT_TARGETS.includes(target);
+}
+function formatInvalidTargetMessage(target) {
+  return `Invalid target: ${target}. Valid targets: ${VALID_EXPORT_TARGETS.join(", ")}`;
+}
+
+// src/commands/validate.ts
+var XAPI_TARGETS = ["xapi", "cmi5"];
+async function validateCommand(options) {
+  if (options?.target !== void 0 && !isValidExportTarget(options.target)) {
+    console.error(pc3.red(formatInvalidTargetMessage(options.target)));
+    process.exit(1);
+  }
   const courseDir = findCourseDir();
   const result = await validateCourse3(courseDir);
+  const issues = [...result.issues];
+  const target = options?.target;
+  const needsXapiCheck = target && XAPI_TARGETS.includes(target) || Boolean(result.manifest?.tracking?.xapi);
+  if (needsXapiCheck && result.manifest) {
+    issues.push(...validateXapiTracking(result.manifest));
+  }
   if (result.manifest) {
     console.log(
       pc3.dim(`Course: ${result.manifest.title} v${result.manifest.version}`)
@@ -496,11 +582,13 @@ async function validateCommand() {
     console.log(pc3.dim(`Lessons: ${result.manifest.lessons.length}`));
     console.log();
   }
-  for (const issue of result.issues) {
+  const hasErrors = issues.some((i) => i.severity === "error");
+  const valid = result.valid && !hasErrors;
+  for (const issue of issues) {
     const icon = issue.severity === "error" ? pc3.red("\u2717") : pc3.yellow("!");
     console.log(`${icon} ${issue.path}: ${issue.message}`);
   }
-  if (result.valid) {
+  if (valid) {
     console.log(pc3.green("\u2713 Course validation passed"));
     process.exit(0);
   } else {
@@ -524,12 +612,16 @@ import {
 var zipPackagers = {
   scorm12: { package: packageCourse },
   scorm2004: { package: packageCourse },
-  standalone: { package: packageCourse }
+  standalone: { package: packageCourse },
+  xapi: { package: packageCourse },
+  cmi5: { package: packageCourse }
 };
 var dirPackagers = {
   scorm12: { package: packageStandaloneDir },
   scorm2004: { package: packageScorm2004Dir },
-  standalone: { package: packageStandaloneDir }
+  standalone: { package: packageStandaloneDir },
+  xapi: { package: packageStandaloneDir },
+  cmi5: { package: packageStandaloneDir }
 };
 function getZipPackager(target) {
   return zipPackagers[target];
@@ -539,18 +631,13 @@ function getDirPackager(target) {
 }
 
 // src/commands/build.ts
-import { validateCourse as validateCourse4 } from "@lxpack/validators";
-var VALID_TARGETS = ["scorm12", "scorm2004", "standalone"];
+import { validateCourse as validateCourse4, validateXapiTracking as validateXapiTracking2 } from "@lxpack/validators";
 async function buildCommand(options) {
   const courseDir = findCourseDir();
   const config = await loadLxpackConfig(courseDir);
   const target = options.target ?? config?.exports?.defaultTarget ?? "scorm12";
-  if (!VALID_TARGETS.includes(target)) {
-    console.error(
-      pc4.red(
-        `Invalid target: ${target}. Valid targets: ${VALID_TARGETS.join(", ")}`
-      )
-    );
+  if (!isValidExportTarget(target)) {
+    console.error(pc4.red(formatInvalidTargetMessage(target)));
     process.exit(1);
   }
   const ctx = await loadValidatedCourseContext(courseDir);
@@ -561,6 +648,16 @@ async function buildCommand(options) {
     process.exit(1);
   }
   const { manifest, assessmentBundle } = ctx;
+  if (target === "xapi" || target === "cmi5") {
+    const xapiIssues = validateXapiTracking2(manifest);
+    if (xapiIssues.length > 0) {
+      console.error(pc4.red("Cannot build: course validation failed"));
+      for (const issue of xapiIssues) {
+        console.error(`  ${issue.path}: ${issue.message}`);
+      }
+      process.exit(1);
+    }
+  }
   const [{ clientJs, css }, componentsBundleJs] = await Promise.all([
     readRuntimeBundle(),
     readComponentsBundle()
@@ -588,7 +685,7 @@ async function buildCommand(options) {
     console.log(`  Output: ${result.outputDir}`);
     console.log(`  Files: ${result.fileCount}`);
   } else {
-    const defaultName = target === "standalone" ? `${slug}-standalone.zip` : target === "scorm2004" ? `${slug}-scorm2004.zip` : `${slug}-scorm12.zip`;
+    const defaultName = target === "standalone" ? `${slug}-standalone.zip` : target === "scorm2004" ? `${slug}-scorm2004.zip` : target === "xapi" ? `${slug}-xapi.zip` : target === "cmi5" ? `${slug}-cmi5.zip` : `${slug}-scorm12.zip`;
     const outputPath = options.output ?? join5(outputRoot, defaultName);
     const result = await getZipPackager(target).package({
       ...packageOptions,
@@ -615,12 +712,15 @@ function createCliProgram() {
       host: options.host
     });
   });
-  program.command("validate").description("Validate course structure and assets").action(async () => {
-    await validateCommand();
+  program.command("validate").description("Validate course structure and assets").option(
+    "-t, --target <target>",
+    "Also validate export requirements for scorm12, scorm2004, standalone, xapi, or cmi5"
+  ).action(async (options) => {
+    await validateCommand(options);
   });
   program.command("build").description("Build LMS-compatible package").option(
     "-t, --target <target>",
-    "Export target: scorm12, scorm2004, standalone",
+    "Export target: scorm12, scorm2004, standalone, xapi, cmi5",
     void 0
   ).option("-o, --output <path>", "Output file or directory path").option("--dir", "Output as directory instead of ZIP").action(
     async (options) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lxpack/cli",
-  "version": "0.2.2",
+  "version": "0.3.0",
   "description": "CLI for building, validating, and packaging LXPack courses",
   "license": "Apache-2.0",
   "repository": {
@@ -39,10 +39,10 @@
     "picocolors": "^1.1.1",
     "yaml": "^2.7.0",
     "zod": "^3.24.2",
-    "@lxpack/components": "0.2.2",
-    "@lxpack/runtime": "0.2.2",
-    "@lxpack/validators": "0.2.2",
-    "@lxpack/scorm": "0.2.2"
+    "@lxpack/components": "0.3.0",
+    "@lxpack/runtime": "0.3.0",
+    "@lxpack/scorm": "0.3.0",
+    "@lxpack/validators": "0.3.0"
   },
   "devDependencies": {
     "@types/node": "^22.13.10",