@lessonkit/cli 0.9.2 → 1.0.0

package/README.md

@@ -1,55 +1,41 @@
-# `@lessonkit/cli`
+# @lessonkit/cli
 
-[![CI](https://github.com/eddiethedean/lessonkit/actions/workflows/ci.yml/badge.svg)](https://github.com/eddiethedean/lessonkit/actions/workflows/ci.yml)
-[![Documentation](https://readthedocs.org/projects/lessonkit/badge/?version=latest)](https://lessonkit.readthedocs.io/en/latest/)
 [![npm](https://img.shields.io/npm/v/@lessonkit/cli.svg)](https://www.npmjs.com/package/@lessonkit/cli)
+[![Documentation](https://readthedocs.org/projects/lessonkit/badge/?version=latest)](https://lessonkit.readthedocs.io/en/latest/reference/cli.html)
 [![License](https://img.shields.io/github/license/eddiethedean/lessonkit)](https://github.com/eddiethedean/lessonkit/blob/main/LICENSE)
 
-LessonKit CLI — scaffold, dev, build, and package learning experiences.
-
-**Docs:** [CLI reference](https://lessonkit.readthedocs.io/en/latest/reference/cli.html) · [Packaging & CLI guide](https://lessonkit.readthedocs.io/en/latest/guides/react-developers/packaging-and-cli.html) · [Vibe coding: shipping to LMS](https://lessonkit.readthedocs.io/en/latest/guides/vibe-coding/shipping-to-lms.html)
+Scaffold, develop, build, and package LessonKit courses. Node.js **18+**.
 
 ## Install
 
 ```bash
 npm install -g @lessonkit/cli
-# or
+# or one-shot:
 npx @lessonkit/cli init my-course
 ```
 
-**Node.js:** dev/build on Node 18+. LMS packaging targets require **Node.js 20+**.
-
-## Quick start
+## Commands
 
 ```bash
-lessonkit init my-course
-cd my-course
-lessonkit dev
-lessonkit build
-lessonkit package --target scorm12
+lessonkit init my-course    # scaffold Vite + React project
+lessonkit dev               # Vite dev server
+lessonkit build             # production build → dist/
+lessonkit package --target scorm12   # LMS artifact
 ```
 
-## Commands
-
-| Command | Description |
-|---------|-------------|
-| `lessonkit init [name]` | Scaffold a Vite + React project |
-| `lessonkit dev` | Run Vite dev server |
-| `lessonkit build` | Production Vite build |
-| `lessonkit package --target <target>` | Build or package for web / LMS |
-| `lessonkit publish` | Stub — see [`RELEASING.md`](https://github.com/eddiethedean/lessonkit/blob/main/RELEASING.md) |
-
-### Package targets
+| Target | Output |
+| --- | --- |
+| `react-vite` | Vite build only |
+| `scorm12`, `scorm2004` | SCORM package |
+| `standalone` | Self-contained web bundle |
+| `xapi`, `cmi5` | xAPI / cmi5 packages |
 
-- `react-vite` — Vite production build → `dist/`
-- `scorm12`, `scorm2004`, `xapi`, `cmi5`, `standalone` — via `@lessonkit/lxpack`
+Every project includes a root `lessonkit.json` manifest (`schemaVersion: 1`).
 
-## Project manifest
+## Docs
 
-Projects include a `lessonkit.json` at the root. See the [CLI reference](https://lessonkit.readthedocs.io/en/latest/reference/cli.html) for the schema, flags, exit codes, and JSON output mode.
+[CLI reference](https://lessonkit.readthedocs.io/en/latest/reference/cli.html) · [Packaging guide](https://lessonkit.readthedocs.io/en/latest/guides/react-developers/packaging-and-cli.html) · [Template source](https://github.com/eddiethedean/lessonkit/tree/main/templates/vite-react)
 
-## Related
+## License
 
-- [Packaging reference](https://lessonkit.readthedocs.io/en/latest/reference/packaging.html) — LXPack output layout
-- [React quickstart](https://lessonkit.readthedocs.io/en/latest/guides/react-developers/quickstart.html)
-- [`templates/vite-react`](https://github.com/eddiethedean/lessonkit/tree/main/templates/vite-react) — starter template
+Apache-2.0

package/dist/bin.js

@@ -5,6 +5,7 @@ import { createRequire } from "module";
 import { Command } from "commander";
 
 // src/commands/init.ts
+import { slugifyId } from "@lessonkit/core";
 import { cp, mkdir, readdir, readFile, writeFile } from "fs/promises";
 import { existsSync } from "fs";
 import { basename, dirname, join, resolve } from "path";
@@ -101,9 +102,6 @@ function getTemplateDir() {
   }
   return candidates[0];
 }
-function slugifyName(name) {
-  return name.trim().toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 64) || "my-course";
-}
 async function isDirEmpty(dir) {
   if (!existsSync(dir)) return true;
   const entries = await readdir(dir);
@@ -153,14 +151,14 @@ async function applyTemplateSubstitutions(projectDir, projectName, slug) {
 }
 async function runInit(opts, logger) {
   const cwd = process.cwd();
-  const rawName = opts.name ?? (opts.here ? slugifyName(basename(process.cwd()) || "my-course") : void 0);
+  const rawName = opts.name ?? (opts.here ? slugifyId(basename(process.cwd()) || "my-course") : void 0);
   if (!rawName && !opts.here) {
     throw new CliError("Project name is required. Usage: lessonkit init <name> or lessonkit init --here", {
       code: "INVALID_PROJECT",
       exitCode: EXIT_INVALID_PROJECT
     });
   }
-  const slug = slugifyName(rawName ?? "my-course");
+  const slug = slugifyId(rawName ?? "my-course");
   const projectName = rawName ?? slug;
   const projectDir = opts.here ? cwd : resolve(cwd, slug);
   if (!opts.here && existsSync(projectDir)) {
@@ -211,18 +209,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;
   }
@@ -255,124 +248,66 @@ 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 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 parsed = parseLessonkitManifest(raw, configPath, projectRoot);
+  if (!parsed.ok) {
+    throwManifestCliError(configPath, parsed.issues);
   }
-  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 {
+    root: projectRoot,
+    schemaVersion: 1,
+    name: parsed.manifest.name,
+    course: parsed.manifest.course,
+    paths: parsed.manifest.paths
+  };
+}
+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);
@@ -390,7 +325,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.`,
@@ -398,28 +333,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 }
     );
   }
@@ -481,17 +413,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 };
 }
 
@@ -526,7 +460,7 @@ async function runPackage(opts) {
     }
     return { ok: true, target, projectRoot: project.root, distDir };
   }
-  assertNode20ForLxpack();
+  assertNode18ForLxpack();
   if (!opts.noBuild || !existsSync3(distDir)) {
     await runBuild({ cwd: project.root, json: opts.json });
   }
@@ -600,7 +534,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",
+    "With --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),
@@ -634,13 +571,27 @@ 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.target === "react-vite" && "distDir" in result) {
+            logger.log(`Built react-vite \u2192 ${result.distDir}`);
+          } else if ("outputPath" in result || "outputDir" in result) {
+            const dest = result.outputPath ?? result.outputDir;
+            const count = "fileCount" in result ? result.fileCount : void 0;
+            logger.log(
+              `Packaged ${result.target}${dest ? ` \u2192 ${dest}` : ""}${count != null ? ` (${count} files)` : ""}`
+            );
+          }
+        }
+        return result;
+      },
       logger,
       Boolean(opts.json)
     );