@lxpack/cli 0.1.0 → 0.1.1

package/README.md

@@ -0,0 +1,114 @@
+# @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.
+
+| Related | Package |
+|---------|---------|
+| Validation | [`@lxpack/validators`](../validators/README.md) |
+| Browser runtime | [`@lxpack/runtime`](../runtime/README.md) |
+| Export / ZIP | [`@lxpack/scorm`](../scorm/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
+```
+
+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) 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.
+
+### 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
+  assets/
+  .lxpack/             # build output (generated)
+```
+
+### `lxpack.config.json`
+
+```json
+{
+  "defaultTarget": "scorm12",
+  "output": {
+    "dir": ".lxpack"
+  }
+}
+```
+
+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`, and `@lxpack/runtime` 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)
+- [Changelog](https://github.com/eddiethedean/lxpack/blob/main/CHANGELOG.md)
+
+## License
+
+Apache-2.0

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"));
 }
@@ -112,6 +109,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}}
@@ -234,7 +252,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) {
@@ -281,11 +299,23 @@ 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
+    } : {}
+  });
+}
+async function createPreviewServer(courseDir, manifest, assessmentBundle) {
   const runtimeDir = getRuntimeAssetsDir();
   const app = Fastify({ logger: false });
   await app.register(fastifyStatic, {
@@ -299,12 +329,8 @@ async function createPreviewServer(courseDir, manifest) {
     decorateReply: false
   });
   const stylesCss = await loadPreviewStyles(runtimeDir);
+  const config = buildPreviewConfig(manifest, assessmentBundle);
   app.get("/", async (_req, reply) => {
-    const config = JSON.stringify({
-      manifest,
-      baseUrl: "/course",
-      mode: "preview"
-    });
     const html = `<!DOCTYPE html>
 <html lang="en">
 <head>
@@ -315,8 +341,9 @@ 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>
   <script type="module" src="/runtime/client.js"></script>
 </body>
@@ -336,13 +363,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,8 +450,11 @@ 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"];
 async function buildCommand(options) {
@@ -432,41 +470,46 @@ 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 manifest = validation.manifest;
+  const assessmentBundle = await buildRuntimeAssessmentBundle2(
+    courseDir,
+    manifest
+  );
   const { clientJs, css } = await readRuntimeBundle();
-  const slug = manifest.title.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "") || "course";
+  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,
+    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 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}`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lxpack/cli",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "CLI for building, validating, and packaging LXPack courses",
   "license": "Apache-2.0",
   "repository": {
@@ -39,9 +39,9 @@
     "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.1.1",
+    "@lxpack/scorm": "0.1.1",
+    "@lxpack/validators": "0.1.1"
   },
   "devDependencies": {
     "@types/node": "^22.13.10",