@lessonkit/cli 0.9.3 → 1.0.1

package/dist/index.js

@@ -156,6 +156,12 @@ async function runInit(opts, logger) {
       exitCode: EXIT_INVALID_PROJECT
     });
   }
+  if (opts.force && !opts.here) {
+    throw new CliError("--force requires --here (initialize in the current directory).", {
+      code: "INVALID_PROJECT",
+      exitCode: EXIT_INVALID_PROJECT
+    });
+  }
   const slug = slugifyId(rawName ?? "my-course");
   const projectName = rawName ?? slug;
   const projectDir = opts.here ? cwd : resolve(cwd, slug);
@@ -207,18 +213,13 @@ async function runInit(opts, logger) {
 import { readFileSync, existsSync as existsSync2 } from "fs";
 import { readFile as readFile2 } from "fs/promises";
 import { dirname as dirname2, join as join2, parse, resolve as resolve2 } from "path";
-import { validateDescriptor, validateProjectPaths } from "@lessonkit/lxpack";
+import { parseLessonkitManifest } from "@lessonkit/lxpack";
 var LESSONKIT_JSON = "lessonkit.json";
 var PACKAGE_JSON = "package.json";
-var DEFAULT_PATHS = {
-  spaDistDir: "dist",
-  lxpackOutDir: ".lxpack/course",
-  outputBaseDir: ".lxpack/out"
-};
 function isProjectManifest(configPath) {
   try {
     const raw = JSON.parse(readFileSync(configPath, "utf8"));
-    return raw.schemaVersion === 1 && typeof raw.name === "string" && raw.course !== null && typeof raw.course === "object";
+    return raw.schemaVersion === 1 && typeof raw.name === "string" && raw.course !== null && typeof raw.course === "object" && !Array.isArray(raw.course);
   } catch {
     return false;
   }
@@ -251,124 +252,63 @@ async function loadLessonkitJson(projectRoot) {
       exitCode: EXIT_INVALID_PROJECT
     });
   }
-  if (!raw || typeof raw !== "object") {
-    throw new CliError(`${configPath} must be a JSON object.`, {
-      code: "INVALID_PROJECT",
-      exitCode: EXIT_INVALID_PROJECT
-    });
+  const parsed = parseLessonkitManifest(raw, configPath, projectRoot);
+  if (!parsed.ok) {
+    throwManifestCliError(configPath, parsed.issues);
   }
-  const config = raw;
-  const schemaVersion = config.schemaVersion;
-  if (schemaVersion !== 1) {
-    throw new CliError(`${configPath}: schemaVersion must be 1 (got ${String(schemaVersion)}).`, {
-      code: "INVALID_PROJECT",
-      exitCode: EXIT_INVALID_PROJECT
-    });
-  }
-  const name = config.name;
-  if (typeof name !== "string" || !name.trim()) {
-    throw new CliError(`${configPath}: "name" must be a non-empty string.`, {
-      code: "INVALID_PROJECT",
-      exitCode: EXIT_INVALID_PROJECT
-    });
+  return {
+    ...parsed.manifest,
+    root: projectRoot
+  };
+}
+function throwManifestCliError(configPath, issues) {
+  const layoutIssue = issues.find((i) => i.path === "course.layout");
+  if (layoutIssue?.message.includes("per-lesson-spa")) {
+    throw new CliError(
+      `${configPath}: per-lesson-spa layout is not supported by lessonkit package yet. Use single-spa or package via @lessonkit/lxpack directly.`,
+      { code: "INVALID_PROJECT", exitCode: EXIT_INVALID_PROJECT }
+    );
   }
-  const courseRaw = config.course;
-  if (!courseRaw || typeof courseRaw !== "object") {
-    throw new CliError(`${configPath}: "course" must be an object.`, {
+  const lessonsIssue = issues.find((i) => i.path === "course.lessons");
+  if (lessonsIssue) {
+    throw new CliError(`${configPath}: "course.lessons" must be an array.`, {
       code: "INVALID_PROJECT",
       exitCode: EXIT_INVALID_PROJECT
     });
   }
-  const courseObj = courseRaw;
-  if (courseObj.lessons !== void 0 && !Array.isArray(courseObj.lessons)) {
-    throw new CliError(`${configPath}: "course.lessons" must be an array.`, {
+  const spaDistTypeIssue = issues.find((i) => i.path === "paths.spaDistDir");
+  if (spaDistTypeIssue && spaDistTypeIssue.message.includes("non-empty string")) {
+    throw new CliError(`${configPath}: "paths.spaDistDir" must be a non-empty string.`, {
       code: "INVALID_PROJECT",
       exitCode: EXIT_INVALID_PROJECT
     });
   }
-  if (courseObj.assessments !== void 0 && !Array.isArray(courseObj.assessments)) {
-    throw new CliError(`${configPath}: "course.assessments" must be an array.`, {
+  const courseSpaIssue = issues.find((i) => i.path === "course.spaDistDir");
+  if (courseSpaIssue) {
+    throw new CliError(`${configPath}: ${courseSpaIssue.message}`, {
       code: "INVALID_PROJECT",
       exitCode: EXIT_INVALID_PROJECT
     });
   }
-  const validation = validateDescriptor(courseRaw);
-  if (!validation.ok) {
-    throw new CliError(`${configPath}: invalid course descriptor.`, {
+  if (issues.some((i) => i.path.startsWith("paths."))) {
+    throw new CliError(`${configPath}: invalid paths.`, {
       code: "INVALID_PROJECT",
       exitCode: EXIT_INVALID_PROJECT,
-      issues: validation.issues.map((i) => ({
-        path: i.path,
-        message: i.message
-      }))
+      issues: issues.map((i) => ({ path: i.path, message: i.message }))
     });
   }
-  if (validation.descriptor.layout === "per-lesson-spa") {
-    throw new CliError(
-      `${configPath}: per-lesson-spa layout is not supported by lessonkit package yet. Use single-spa or package via @lessonkit/lxpack directly.`,
-      { code: "INVALID_PROJECT", exitCode: EXIT_INVALID_PROJECT }
-    );
-  }
-  const pathsRaw = config.paths;
-  const paths = { ...DEFAULT_PATHS };
-  if (pathsRaw !== void 0 && (typeof pathsRaw !== "object" || pathsRaw === null)) {
-    throw new CliError(`${configPath}: "paths" must be an object.`, {
+  const schemaIssue = issues.find((i) => i.path === "schemaVersion");
+  if (schemaIssue) {
+    throw new CliError(`${configPath}: schemaVersion must be 1 (got ${schemaIssue.message.replace(/^must be 1 \(got /, "").replace(/\)$/, "")}).`, {
       code: "INVALID_PROJECT",
       exitCode: EXIT_INVALID_PROJECT
     });
   }
-  if (pathsRaw && typeof pathsRaw === "object") {
-    const p = pathsRaw;
-    if (p.spaDistDir !== void 0) {
-      if (typeof p.spaDistDir !== "string" || !p.spaDistDir.trim()) {
-        throw new CliError(`${configPath}: "paths.spaDistDir" must be a non-empty string.`, {
-          code: "INVALID_PROJECT",
-          exitCode: EXIT_INVALID_PROJECT
-        });
-      }
-      paths.spaDistDir = p.spaDistDir;
-    }
-    if (p.lxpackOutDir !== void 0) {
-      if (typeof p.lxpackOutDir !== "string" || !p.lxpackOutDir.trim()) {
-        throw new CliError(`${configPath}: "paths.lxpackOutDir" must be a non-empty string.`, {
-          code: "INVALID_PROJECT",
-          exitCode: EXIT_INVALID_PROJECT
-        });
-      }
-      paths.lxpackOutDir = p.lxpackOutDir;
-    }
-    if (p.outputBaseDir !== void 0) {
-      if (typeof p.outputBaseDir !== "string" || !p.outputBaseDir.trim()) {
-        throw new CliError(`${configPath}: "paths.outputBaseDir" must be a non-empty string.`, {
-          code: "INVALID_PROJECT",
-          exitCode: EXIT_INVALID_PROJECT
-        });
-      }
-      paths.outputBaseDir = p.outputBaseDir;
-    }
-  }
-  const courseSpaDistDir = validation.descriptor.spaDistDir?.trim();
-  if (courseSpaDistDir && courseSpaDistDir !== paths.spaDistDir) {
-    throw new CliError(
-      `${configPath}: "course.spaDistDir" (${courseSpaDistDir}) differs from "paths.spaDistDir" (${paths.spaDistDir}). Use paths.spaDistDir for CLI build and package.`,
-      { code: "INVALID_PROJECT", exitCode: EXIT_INVALID_PROJECT }
-    );
-  }
-  const pathIssues = validateProjectPaths(projectRoot, paths);
-  if (pathIssues.length) {
-    throw new CliError(`${configPath}: invalid paths.`, {
-      code: "INVALID_PROJECT",
-      exitCode: EXIT_INVALID_PROJECT,
-      issues: pathIssues
-    });
-  }
-  return {
-    root: projectRoot,
-    schemaVersion: 1,
-    name,
-    course: validation.descriptor,
-    paths
-  };
+  throw new CliError(`${configPath}: invalid lessonkit manifest.`, {
+    code: "INVALID_PROJECT",
+    exitCode: EXIT_INVALID_PROJECT,
+    issues: issues.map((i) => ({ path: i.path, message: i.message }))
+  });
 }
 async function loadProject(cwd = process.cwd()) {
   const root = findProjectRoot(cwd);
@@ -386,7 +326,7 @@ async function readPackageJson(projectRoot) {
   }
 }
 function assertViteProject(pkg, projectRoot) {
-  const vite = pkg.devDependencies?.vite ?? pkg.dependencies?.vite ?? (existsSync2(join2(projectRoot, "node_modules", ".bin", "vite")) || existsSync2(join2(projectRoot, "node_modules", ".bin", "vite.cmd")) ? "present" : void 0);
+  const vite = pkg.devDependencies?.vite ?? pkg.dependencies?.vite ?? (existsSync2(join2(projectRoot, "node_modules", "vite", "bin", "vite.js")) || existsSync2(join2(projectRoot, "node_modules", ".bin", "vite")) || existsSync2(join2(projectRoot, "node_modules", ".bin", "vite.cmd")) ? "present" : void 0);
   if (!vite) {
     throw new CliError(
       `No Vite dependency found in ${join2(projectRoot, PACKAGE_JSON)}. LessonKit projects require Vite.`,
@@ -394,28 +334,25 @@ function assertViteProject(pkg, projectRoot) {
     );
   }
 }
-function resolveViteBin(projectRoot) {
+function resolveViteJs(projectRoot) {
   let dir = resolve2(projectRoot);
   const fsRoot = parse(dir).root;
   while (true) {
-    const binDir = join2(dir, "node_modules", ".bin");
-    const bin = join2(binDir, "vite");
-    if (existsSync2(bin)) return bin;
-    const binCmd = join2(binDir, "vite.cmd");
-    if (existsSync2(binCmd)) return binCmd;
+    const viteJs = join2(dir, "node_modules", "vite", "bin", "vite.js");
+    if (existsSync2(viteJs)) return viteJs;
     if (dir === fsRoot) break;
     dir = dirname2(dir);
   }
   throw new CliError(
-    `Vite binary not found near ${projectRoot}. Run npm install in the project first.`,
+    `Vite not found near ${projectRoot}. Run npm install in the project first.`,
     { code: "INVALID_PROJECT", exitCode: EXIT_INVALID_PROJECT }
   );
 }
-function assertNode20ForLxpack() {
+function assertNode18ForLxpack() {
   const major = Number(process.versions.node.split(".")[0]);
-  if (major < 20) {
+  if (major < 18) {
     throw new CliError(
-      `LMS packaging requires Node.js 20+ (current: ${process.versions.node}). See docs/PACKAGING.md.`,
+      `LMS packaging requires Node.js 18+ (current: ${process.versions.node}). See docs/PACKAGING.md.`,
       { code: "NODE_VERSION", exitCode: EXIT_INVALID_PROJECT }
     );
   }
@@ -424,6 +361,18 @@ function assertNode20ForLxpack() {
 // src/lib/paths.ts
 import { resolve as resolve3 } from "path";
 import { resolveSafePackageOutputOverride } from "@lessonkit/lxpack";
+
+// src/lib/targetTypes.ts
+var PACKAGE_TARGETS = [
+  "react-vite",
+  "scorm12",
+  "scorm2004",
+  "xapi",
+  "cmi5",
+  "standalone"
+];
+
+// src/lib/paths.ts
 function resolveDistDir(project) {
   return resolve3(project.root, project.paths.spaDistDir);
 }
@@ -454,14 +403,6 @@ function resolveViteBuildArgs(project) {
   }
   return args;
 }
-var PACKAGE_TARGETS = [
-  "react-vite",
-  "scorm12",
-  "scorm2004",
-  "xapi",
-  "cmi5",
-  "standalone"
-];
 function parsePackageTarget(value) {
   if (!value) {
     throw new Error("TARGET_REQUIRED");
@@ -477,17 +418,19 @@ async function runDev(opts) {
   const project = await loadProject(opts.cwd ?? process.cwd());
   const pkg = await readPackageJson(project.root);
   assertViteProject(pkg, project.root);
-  const viteBin = resolveViteBin(project.root);
-  await runCommand(viteBin, opts.viteArgs ?? [], { cwd: project.root });
+  const viteJs = resolveViteJs(project.root);
+  await runCommand(process.execPath, [viteJs, ...opts.viteArgs ?? []], { cwd: project.root });
   return { ok: true, command: "dev", projectRoot: project.root };
 }
 async function runBuild(opts) {
   const project = await loadProject(opts.cwd ?? process.cwd());
   const pkg = await readPackageJson(project.root);
   assertViteProject(pkg, project.root);
-  const viteBin = resolveViteBin(project.root);
+  const viteJs = resolveViteJs(project.root);
   const buildArgs = resolveViteBuildArgs(project);
-  await runCommand(viteBin, [...buildArgs, ...opts.viteArgs ?? []], { cwd: project.root });
+  await runCommand(process.execPath, [viteJs, ...buildArgs, ...opts.viteArgs ?? []], {
+    cwd: project.root
+  });
   return { ok: true, command: "build", projectRoot: project.root };
 }
 
@@ -510,8 +453,17 @@ async function runPackage(opts) {
   }
   const project = await loadProject(opts.cwd ?? process.cwd());
   const distDir = resolveDistDir(project);
+  if (opts.noBuild && !existsSync3(distDir)) {
+    throw new CliError(
+      `dist directory not found at ${distDir}. Run lessonkit build before packaging with --no-build.`,
+      {
+        code: "INVALID_PROJECT",
+        exitCode: EXIT_INVALID_PROJECT
+      }
+    );
+  }
   if (target === "react-vite") {
-    if (!opts.noBuild || !existsSync3(distDir)) {
+    if (!opts.noBuild) {
       await runBuild({ cwd: project.root, json: opts.json });
     }
     if (!existsSync3(distDir)) {
@@ -520,10 +472,10 @@ async function runPackage(opts) {
         exitCode: EXIT_INVALID_PROJECT
       });
     }
-    return { ok: true, target, projectRoot: project.root, distDir };
+    return { ok: true, command: "package", target, projectRoot: project.root, distDir };
   }
-  assertNode20ForLxpack();
-  if (!opts.noBuild || !existsSync3(distDir)) {
+  assertNode18ForLxpack();
+  if (!opts.noBuild) {
     await runBuild({ cwd: project.root, json: opts.json });
   }
   if (!existsSync3(distDir)) {
@@ -553,6 +505,7 @@ async function runPackage(opts) {
   }
   return {
     ok: true,
+    command: "package",
     target,
     projectRoot: project.root,
     outputPath: result.outputPath,
@@ -596,7 +549,10 @@ async function handleCommand(fn, logger, json) {
 function createProgram(baseLogger = console) {
   const program = new Command();
   program.name("lessonkit").description("LessonKit CLI").version(version);
-  program.command("init").description("Initialize a LessonKit project from the Vite + React template").argument("[name]", "Project directory name").option("--here", "Initialize in the current directory").option("--skip-install", "Skip npm install").option("--force", "Initialize into a non-empty directory").option("--json", "Emit structured JSON result").action(async (name, opts) => {
+  program.command("init").description("Initialize a LessonKit project from the Vite + React template").argument("[name]", "Project directory name").option("--here", "Initialize in the current directory").option("--skip-install", "Skip npm install").option(
+    "--force",
+    "Requires --here: allow init when the directory is empty or contains only dotfiles"
+  ).option("--json", "Emit structured JSON result").action(async (name, opts) => {
     const logger = createLogger({ json: opts.json });
     await handleCommand(
       () => runInit({ name, here: opts.here, skipInstall: opts.skipInstall, force: opts.force, json: opts.json }, logger),
@@ -616,7 +572,9 @@ function createProgram(baseLogger = console) {
       Boolean(opts.json)
     );
   });
-  addCwdAndJson(program.command("build").description("Production Vite build")).action(
+  addCwdAndJson(
+    program.command("build").description("Production Vite build").allowUnknownOption().allowExcessArguments()
+  ).action(
     async (opts, command) => {
       const logger = createLogger({ json: opts.json });
       const viteArgs = command.args;
@@ -630,13 +588,26 @@ function createProgram(baseLogger = console) {
   program.command("package").description("Build or package for web / LMS delivery").requiredOption("--target <target>", `Export target (${PACKAGE_TARGETS.join(", ")})`).option("--cwd <dir>", "Project root directory").option("--no-build", "Skip implicit Vite build for LMS targets").option("--out <path>", "Override output artifact path").option("--json", "Emit structured JSON result").action(async (opts) => {
     const logger = createLogger({ json: opts.json });
     await handleCommand(
-      () => runPackage({
-        target: opts.target,
-        cwd: opts.cwd,
-        noBuild: opts.build === false,
-        out: opts.out,
-        json: opts.json
-      }),
+      async () => {
+        const result = await runPackage({
+          target: opts.target,
+          cwd: opts.cwd,
+          noBuild: opts.build === false,
+          out: opts.out,
+          json: opts.json
+        });
+        if (!opts.json && result.ok) {
+          if (result.command === "package" && result.target === "react-vite") {
+            logger.log(`Built react-vite \u2192 ${result.distDir}`);
+          } else if (result.command === "package") {
+            const dest = result.outputPath ?? result.outputDir;
+            logger.log(
+              `Packaged ${result.target}${dest ? ` \u2192 ${dest}` : ""} (${result.fileCount} files)`
+            );
+          }
+        }
+        return result;
+      },
       logger,
       Boolean(opts.json)
     );

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lessonkit/cli",
-  "version": "0.9.3",
+  "version": "1.0.1",
   "private": false,
   "description": "LessonKit CLI — init, dev, build, and package learning experiences.",
   "license": "Apache-2.0",
@@ -42,8 +42,8 @@
     "lint": "echo \"(no lint configured yet)\""
   },
   "dependencies": {
-    "@lessonkit/core": "0.9.3",
-    "@lessonkit/lxpack": "0.9.3",
+    "@lessonkit/core": "1.0.1",
+    "@lessonkit/lxpack": "1.0.1",
     "commander": "^14.0.1"
   },
   "engines": {

package/template/vite-react/README.md

@@ -1,19 +1,21 @@
-# LessonKit Vite + React template
+# LessonKit starter template
 
-[![Documentation](https://readthedocs.org/projects/lessonkit/badge/?version=latest)](https://lessonkit.readthedocs.io/en/latest/)
-[![License](https://img.shields.io/github/license/eddiethedean/lessonkit)](https://github.com/eddiethedean/lessonkit/blob/main/LICENSE)
+Vite + React scaffold for new LessonKit courses. Created by `lessonkit init`.
 
-Starter template copied by `lessonkit init`. See the [CLI reference](https://lessonkit.readthedocs.io/en/latest/reference/cli.html) and [React quickstart](https://lessonkit.readthedocs.io/en/latest/guides/react-developers/quickstart.html).
-
-## Run
+## Commands
 
 ```bash
 npm install
-npm run dev
+npm run dev          # lessonkit dev
+npm run build        # lessonkit build
+npm run package:scorm12
 ```
 
-## Notes
+## Files
+
+- `src/App.tsx` — course UI (IDs match `lessonkit.json`)
+- `lessonkit.json` — manifest for CLI and LXPack packaging
+
+## Docs
 
-- Depends on [`@lessonkit/react`](https://lessonkit.readthedocs.io/en/latest/guides/react-developers/components-and-hooks.html).
-- Copied by [`@lessonkit/cli`](https://lessonkit.readthedocs.io/en/latest/reference/cli.html) when you run `lessonkit init`.
-- Package for an LMS with the [packaging guide](https://lessonkit.readthedocs.io/en/latest/guides/react-developers/packaging-and-cli.html).
+[CLI reference](https://lessonkit.readthedocs.io/en/latest/reference/cli.html) · [React quickstart](https://lessonkit.readthedocs.io/en/latest/guides/react-developers/quickstart.html) · [Packaging guide](https://lessonkit.readthedocs.io/en/latest/guides/react-developers/packaging-and-cli.html)

package/template/vite-react/lessonkit.json

@@ -15,7 +15,12 @@
         "passingScore": 1
       }
     ],
-    "theme": { "preset": "default" }
+    "theme": { "preset": "default" },
+    "tracking": {
+      "xapi": {
+        "activityIri": "https://example.com/courses/my-course"
+      }
+    }
   },
   "paths": {
     "spaDistDir": "dist",

package/template/vite-react/package.json

@@ -13,16 +13,16 @@
     "test:coverage": "vitest run --coverage --passWithNoTests=false"
   },
   "dependencies": {
-    "@lessonkit/core": "^0.9.3",
-    "@lessonkit/react": "^0.9.3",
-    "@lessonkit/themes": "^0.9.3",
-    "@lessonkit/xapi": "^0.9.3",
+    "@lessonkit/core": "^1.0.1",
+    "@lessonkit/react": "^1.0.1",
+    "@lessonkit/themes": "^1.0.1",
+    "@lessonkit/xapi": "^1.0.1",
     "react": "^18.3.1",
     "react-dom": "^18.3.1"
   },
   "devDependencies": {
-    "@lessonkit/cli": "^0.9.3",
-    "@lessonkit/lxpack": "^0.9.3",
+    "@lessonkit/cli": "^1.0.1",
+    "@lessonkit/lxpack": "^1.0.1",
     "@testing-library/react": "^16.3.0",
     "@types/react": "^18.3.23",
     "@types/react-dom": "^18.3.7",

package/template/vite-react/dist/assets/index-CP3MNJ8s.css

@@ -1 +0,0 @@
-html,body{height:100%}body{margin:0;background:var(--lk-color-background);color:var(--lk-color-foreground);font-family:var(--lk-font-family);font-size:var(--lk-font-size-base);line-height:var(--lk-line-height-base)}.app-shell{margin:0 auto;padding:var(--lk-space-xl) var(--lk-space-lg);max-width:720px}section,article{border:1px solid var(--lk-color-border);border-radius:var(--lk-radius-lg);padding:var(--lk-space-lg);margin:var(--lk-space-md) 0;background:var(--lk-color-panel);box-shadow:var(--lk-shadow-md)}h1,h2{margin:0 0 var(--lk-space-sm);font-weight:var(--lk-font-weight-strong)}button{border:1px solid var(--lk-color-border);background:var(--lk-color-panel);color:var(--lk-color-foreground);border-radius:var(--lk-radius-md);padding:var(--lk-space-sm) var(--lk-space-md);font-weight:var(--lk-font-weight-strong);cursor:pointer}input[type=radio]{accent-color:var(--lk-color-primary)}label{display:block;margin:var(--lk-space-xs) 0}