@lxpack/cli 0.1.0 → 0.2.0

package/README.md

@@ -0,0 +1,127 @@
+# @lxpack/cli
+
+[![npm version](https://img.shields.io/npm/v/@lxpack/cli)](https://www.npmjs.com/package/@lxpack/cli)
+[![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/)
+
+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.0**).
+
+| Related | Package |
+|---------|---------|
+| Validation | [`@lxpack/validators`](../validators/README.md) |
+| Browser runtime | [`@lxpack/runtime`](../runtime/README.md) |
+| Export / ZIP | [`@lxpack/scorm`](../scorm/README.md) |
+| Lesson widgets | [`@lxpack/components`](../components/README.md) |
+
+## Install
+
+```bash
+npm install -g @lxpack/cli
+# or: pnpm add -g @lxpack/cli
+```
+
+Requires Node.js 20+.
+
+## Quick start
+
+```bash
+lxpack init my-course
+cd my-course
+lxpack preview          # http://127.0.0.1:3847 by default
+lxpack validate
+lxpack build --target scorm12
+lxpack build --target scorm2004
+```
+
+Output lands in `.lxpack/` unless overridden by `-o` or `lxpack.config.json`.
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `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 |
+| `build` | Package for LMS or standalone export |
+
+### `build` options
+
+| Option | Description |
+|--------|-------------|
+| `-t, --target <target>` | `scorm12` (default), `scorm2004`, or `standalone` |
+| `-o, --output <path>` | Output ZIP file or directory |
+| `--dir` | Write an unpacked directory instead of a ZIP |
+
+`build` and `preview` use the same validation rules: errors fail the command (exit code 1). `build` reuses the validated manifest and bakes a sanitized [assessment bundle](../validators/README.md#assessment-packaging) into the exported HTML config.
+
+**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.
+
+### Course discovery
+
+Commands walk up from the current working directory until they find `course.yaml`. Run them from inside your course project (or a subdirectory).
+
+### Path safety
+
+- `init --dir` must be a relative path that stays inside the current working directory.
+- `lxpack.config.json` `output.dir` is resolved relative to the course root with the same containment rules.
+
+## Course layout
+
+```text
+my-course/
+  course.yaml
+  lxpack.config.json   # optional: defaultTarget, output
+  lessons/
+  interactions/
+  assessments/         # authoring only — omitted from export ZIPs
+  components/          # optional widget overrides
+  assets/
+  .lxpack/             # build output (generated)
+```
+
+`init` scaffolds commented examples for `variables`, `flow`, and `type: component` lessons. See [branching-demo](https://github.com/eddiethedean/lxpack/tree/main/examples/branching-demo) for a full v0.2 course.
+
+### `lxpack.config.json`
+
+```json
+{
+  "defaultTarget": "scorm12",
+  "output": {
+    "dir": ".lxpack"
+  }
+}
+```
+
+Use `"defaultTarget": "scorm2004"` when your LMS expects SCORM 2004 4th Edition packages.
+
+See the [root README](https://github.com/eddiethedean/lxpack#course-structure) for a full `course.yaml` example.
+
+## Programmatic use
+
+The CLI is built with [Commander](https://github.com/tj/commander.js). For library integration, import from the built package or depend on `@lxpack/validators`, `@lxpack/scorm`, `@lxpack/runtime`, and `@lxpack/components` directly.
+
+## Development
+
+From the monorepo root:
+
+```bash
+pnpm --filter @lxpack/cli build
+pnpm --filter @lxpack/cli test
+pnpm --filter @lxpack/cli typecheck
+```
+
+## Links
+
+- [LXPack repository](https://github.com/eddiethedean/lxpack)
+- [Documentation index](https://github.com/eddiethedean/lxpack/blob/main/docs/README.md)
+- [Roadmap & phases](https://github.com/eddiethedean/lxpack/blob/main/docs/ROADMAP.md)
+- [Changelog](https://github.com/eddiethedean/lxpack/blob/main/CHANGELOG.md)
+
+## License
+
+Apache-2.0

package/dist/cli.d.ts

@@ -3,11 +3,11 @@ import { z } from 'zod';
 
 declare const lxpackConfigSchema: z.ZodObject<{
     exports: z.ZodOptional<z.ZodObject<{
-        defaultTarget: z.ZodOptional<z.ZodEnum<["scorm12", "standalone"]>>;
+        defaultTarget: z.ZodOptional<z.ZodEnum<["scorm12", "scorm2004", "standalone"]>>;
     }, "strip", z.ZodTypeAny, {
-        defaultTarget?: "scorm12" | "standalone" | undefined;
+        defaultTarget?: "scorm12" | "scorm2004" | "standalone" | undefined;
     }, {
-        defaultTarget?: "scorm12" | "standalone" | undefined;
+        defaultTarget?: "scorm12" | "scorm2004" | "standalone" | undefined;
     }>>;
     output: z.ZodOptional<z.ZodObject<{
         dir: z.ZodOptional<z.ZodString>;
@@ -18,14 +18,14 @@ declare const lxpackConfigSchema: z.ZodObject<{
     }>>;
 }, "strict", z.ZodTypeAny, {
     exports?: {
-        defaultTarget?: "scorm12" | "standalone" | undefined;
+        defaultTarget?: "scorm12" | "scorm2004" | "standalone" | undefined;
     } | undefined;
     output?: {
         dir?: string | undefined;
     } | undefined;
 }, {
     exports?: {
-        defaultTarget?: "scorm12" | "standalone" | undefined;
+        defaultTarget?: "scorm12" | "scorm2004" | "standalone" | undefined;
     } | undefined;
     output?: {
         dir?: string | undefined;

package/dist/cli.js

@@ -17,7 +17,11 @@ import { createRequire } from "module";
 import { dirname, join, resolve } from "path";
 import { stringify as stringifyYaml } from "yaml";
 import { z } from "zod";
-import { loadManifest, formatErrorMessage } from "@lxpack/validators";
+import {
+  loadManifest,
+  formatErrorMessage,
+  isPathContained
+} from "@lxpack/validators";
 var require2 = createRequire(import.meta.url);
 function findCourseDir(startDir = process.cwd()) {
   let dir = resolve(startDir);
@@ -31,13 +35,6 @@ function findCourseDir(startDir = process.cwd()) {
     "No course.yaml found. Run from a course directory or use lxpack init."
   );
 }
-async function loadCourseManifest(courseDir) {
-  const loaded = await loadManifest(courseDir);
-  if (Array.isArray(loaded)) {
-    throw new Error(loaded.map((i) => i.message).join("; "));
-  }
-  return loaded.manifest;
-}
 function getRuntimeAssetsDir() {
   return dirname(require2.resolve("@lxpack/runtime/client"));
 }
@@ -69,9 +66,17 @@ async function readRuntimeBundle(assetsDir = getRuntimeAssetsDir()) {
   }
   return { clientJs, css };
 }
+async function readComponentsBundle() {
+  try {
+    const bundlePath = require2.resolve("@lxpack/components/bundle");
+    return await readFile(bundlePath, "utf-8");
+  } catch {
+    return void 0;
+  }
+}
 var lxpackConfigSchema = z.object({
   exports: z.object({
-    defaultTarget: z.enum(["scorm12", "standalone"]).optional()
+    defaultTarget: z.enum(["scorm12", "scorm2004", "standalone"]).optional()
   }).optional(),
   output: z.object({
     dir: z.string().optional()
@@ -112,6 +117,27 @@ function getCliVersion() {
   const pkg = require2("../package.json");
   return pkg.version;
 }
+function resolvePathInCwd(relativePath) {
+  const cwd = resolve(process.cwd());
+  if (relativePath.startsWith("/") || /^[a-zA-Z]:\\/.test(relativePath)) {
+    throw new Error(
+      "Use a relative path for the output directory (must stay inside the current working directory)"
+    );
+  }
+  const target = resolve(cwd, relativePath);
+  if (!isPathContained(cwd, target)) {
+    throw new Error("Path must be inside the current working directory");
+  }
+  return target;
+}
+function resolveOutputDir(courseDir, outputDir) {
+  const root = resolve(courseDir);
+  const target = resolve(root, outputDir);
+  if (!isPathContained(root, target)) {
+    throw new Error("output.dir in lxpack.config.json must stay inside the course directory");
+  }
+  return target;
+}
 
 // src/commands/init.ts
 var COURSE_YAML_TEMPLATE = `title: {{title}}
@@ -139,6 +165,17 @@ lessons:
 assessments:
   - id: final_quiz
     file: assessments/final.yaml
+
+# Optional Phase 2 features (see examples/branching-demo):
+# variables:
+#   path:
+#     default: intro
+#     type: string
+# flow:
+#   - when:
+#       variable:
+#         eq: [path, advanced]
+#     goto: component_lesson
 `;
 var WELCOME_MD = `# Welcome
 
@@ -234,7 +271,7 @@ function formatTitle(projectName) {
   return projectName.split(/[-_\s]+/).filter(Boolean).map((w) => w.charAt(0).toUpperCase() + w.slice(1)).join(" ");
 }
 async function initCommand(projectName, options = {}) {
-  const targetDir = options.dir ?? projectName;
+  const targetDir = resolvePathInCwd(options.dir ?? projectName);
   const title = formatTitle(projectName);
   const yamlTitle = formatCourseTitleForYaml(title);
   if (existsSync2(join2(targetDir, "course.yaml")) && !options.force) {
@@ -251,7 +288,8 @@ async function initCommand(projectName, options = {}) {
     join2(targetDir, "interactions", "phishing-lab"),
     join2(targetDir, "assets"),
     join2(targetDir, "assessments"),
-    join2(targetDir, "theme")
+    join2(targetDir, "theme"),
+    join2(targetDir, "components")
   ];
   for (const dir of dirs) {
     await mkdir(dir, { recursive: true });
@@ -268,6 +306,7 @@ async function initCommand(projectName, options = {}) {
   await writeFile(join2(targetDir, "assessments", "final.yaml"), FINAL_ASSESSMENT);
   await writeFile(join2(targetDir, "lxpack.config.json"), LXPACK_CONFIG);
   await writeFile(join2(targetDir, "theme", ".gitkeep"), "");
+  await writeFile(join2(targetDir, "components", ".gitkeep"), "");
   console.log(pc.green(`\u2713 Created LXPack course: ${targetDir}`));
   console.log();
   console.log("Next steps:");
@@ -281,11 +320,25 @@ async function initCommand(projectName, options = {}) {
 import Fastify from "fastify";
 import fastifyStatic from "@fastify/static";
 import pc2 from "picocolors";
-import { validateCourse } from "@lxpack/validators";
+import { validateCourse, buildRuntimeAssessmentBundle } from "@lxpack/validators";
+import { safeJsonForHtml } from "@lxpack/scorm";
 async function loadPreviewStyles(assetsDir = getRuntimeAssetsDir()) {
   return loadRuntimeStyles(assetsDir);
 }
-async function createPreviewServer(courseDir, manifest) {
+function buildPreviewConfig(manifest, assessmentBundle) {
+  return safeJsonForHtml({
+    manifest,
+    baseUrl: "/course",
+    mode: "preview",
+    ...assessmentBundle ? {
+      assessments: assessmentBundle.assessments,
+      answerKeys: assessmentBundle.answerKeys,
+      assessmentConfigs: assessmentBundle.configs,
+      assessmentFeedback: assessmentBundle.feedback
+    } : {}
+  });
+}
+async function createPreviewServer(courseDir, manifest, assessmentBundle) {
   const runtimeDir = getRuntimeAssetsDir();
   const app = Fastify({ logger: false });
   await app.register(fastifyStatic, {
@@ -299,12 +352,14 @@ async function createPreviewServer(courseDir, manifest) {
     decorateReply: false
   });
   const stylesCss = await loadPreviewStyles(runtimeDir);
-  app.get("/", async (_req, reply) => {
-    const config = JSON.stringify({
-      manifest,
-      baseUrl: "/course",
-      mode: "preview"
+  const config = buildPreviewConfig(manifest, assessmentBundle);
+  const componentsJs = await readComponentsBundle();
+  if (componentsJs) {
+    app.get("/runtime/components.js", async (_req, reply) => {
+      return reply.type("application/javascript").send(componentsJs);
     });
+  }
+  app.get("/", async (_req, reply) => {
     const html = `<!DOCTYPE html>
 <html lang="en">
 <head>
@@ -315,9 +370,11 @@ async function createPreviewServer(courseDir, manifest) {
 </head>
 <body>
   <div id="lxpack-app"></div>
+  <script type="application/json" id="lxpack-config">${config}</script>
   <script>
-    window.__LXPACK_CONFIG__ = ${config};
+    window.__LXPACK_CONFIG__ = JSON.parse(document.getElementById('lxpack-config').textContent);
   </script>
+  ${componentsJs ? '<script type="module" src="/runtime/components.js"></script>' : ""}
   <script type="module" src="/runtime/client.js"></script>
 </body>
 </html>`;
@@ -336,13 +393,21 @@ async function startPreview(courseDir, _options = {}) {
     process.exit(1);
   }
   if (!validation.valid) {
-    console.log(pc2.yellow("Warning: course has validation issues:"));
+    console.error(pc2.red("Cannot preview: course validation failed"));
     for (const issue of validation.issues) {
-      console.log(`  ${issue.path}: ${issue.message}`);
+      console.error(`  ${issue.path}: ${issue.message}`);
     }
-    console.log();
+    process.exit(1);
   }
-  const app = await createPreviewServer(courseDir, validation.manifest);
+  const assessmentBundle = await buildRuntimeAssessmentBundle(
+    courseDir,
+    validation.manifest
+  );
+  const app = await createPreviewServer(
+    courseDir,
+    validation.manifest,
+    assessmentBundle
+  );
   return { app, validation };
 }
 function resolvePreviewDeps(deps) {
@@ -415,10 +480,13 @@ async function validateCommand() {
 // src/commands/build.ts
 import { mkdir as mkdir2 } from "fs/promises";
 import { join as join3 } from "path";
-import { packageCourse, packageStandaloneDir } from "@lxpack/scorm";
-import { validateCourse as validateCourse3 } from "@lxpack/validators";
+import { packageCourse, packageStandaloneDir, courseSlug } from "@lxpack/scorm";
+import {
+  validateCourse as validateCourse3,
+  buildRuntimeAssessmentBundle as buildRuntimeAssessmentBundle2
+} from "@lxpack/validators";
 import pc4 from "picocolors";
-var VALID_TARGETS = ["scorm12", "standalone"];
+var VALID_TARGETS = ["scorm12", "scorm2004", "standalone"];
 async function buildCommand(options) {
   const courseDir = findCourseDir();
   const config = await loadLxpackConfig(courseDir);
@@ -432,41 +500,50 @@ async function buildCommand(options) {
     process.exit(1);
   }
   const validation = await validateCourse3(courseDir);
-  if (!validation.valid) {
+  if (!validation.valid || !validation.manifest) {
     console.error(pc4.red("Cannot build: course validation failed"));
     for (const issue of validation.issues) {
       console.error(`  ${issue.path}: ${issue.message}`);
     }
     process.exit(1);
   }
-  const manifest = await loadCourseManifest(courseDir);
-  const { clientJs, css } = await readRuntimeBundle();
-  const slug = manifest.title.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "") || "course";
+  const manifest = validation.manifest;
+  const assessmentBundle = await buildRuntimeAssessmentBundle2(
+    courseDir,
+    manifest
+  );
+  const [{ clientJs, css }, componentsBundleJs] = await Promise.all([
+    readRuntimeBundle(),
+    readComponentsBundle()
+  ]);
+  const slug = courseSlug(manifest);
   const outputBase = config?.output?.dir ?? ".lxpack";
-  await mkdir2(join3(courseDir, outputBase), { recursive: true });
+  const outputRoot = resolveOutputDir(courseDir, outputBase);
+  await mkdir2(outputRoot, { recursive: true });
+  const packageOptions = {
+    courseDir,
+    manifest,
+    target,
+    runtimeClientJs: clientJs,
+    runtimeCss: css,
+    componentsBundleJs,
+    assessmentBundle
+  };
   if (options.dir) {
-    const outputDir = options.output ?? join3(courseDir, outputBase, target);
+    const outputDir = options.output ?? join3(outputRoot, target);
     const result = await packageStandaloneDir({
-      courseDir,
-      manifest,
-      outputDir,
-      target,
-      runtimeClientJs: clientJs,
-      runtimeCss: css
+      ...packageOptions,
+      outputDir
     });
     console.log(pc4.green(`\u2713 Built ${target} package`));
     console.log(`  Output: ${result.outputDir}`);
     console.log(`  Files: ${result.fileCount}`);
   } else {
-    const defaultName = target === "standalone" ? `${slug}-standalone.zip` : `${slug}-scorm12.zip`;
-    const outputPath = options.output ?? join3(courseDir, outputBase, defaultName);
+    const defaultName = target === "standalone" ? `${slug}-standalone.zip` : target === "scorm2004" ? `${slug}-scorm2004.zip` : `${slug}-scorm12.zip`;
+    const outputPath = options.output ?? join3(outputRoot, defaultName);
     const result = await packageCourse({
-      courseDir,
-      manifest,
-      outputPath,
-      target,
-      runtimeClientJs: clientJs,
-      runtimeCss: css
+      ...packageOptions,
+      outputPath
     });
     console.log(pc4.green(`\u2713 Built ${target} package`));
     console.log(`  Output: ${result.outputPath}`);
@@ -494,7 +571,7 @@ function createCliProgram() {
   });
   program.command("build").description("Build LMS-compatible package").option(
     "-t, --target <target>",
-    "Export target: scorm12, standalone",
+    "Export target: scorm12, scorm2004, standalone",
     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.1.0",
+  "version": "0.2.0",
   "description": "CLI for building, validating, and packaging LXPack courses",
   "license": "Apache-2.0",
   "repository": {
@@ -39,9 +39,10 @@
     "picocolors": "^1.1.1",
     "yaml": "^2.7.0",
     "zod": "^3.24.2",
-    "@lxpack/runtime": "0.1.0",
-    "@lxpack/scorm": "0.1.0",
-    "@lxpack/validators": "0.1.0"
+    "@lxpack/runtime": "0.2.0",
+    "@lxpack/components": "0.2.0",
+    "@lxpack/scorm": "0.2.0",
+    "@lxpack/validators": "0.2.0"
   },
   "devDependencies": {
     "@types/node": "^22.13.10",