@lessonkit/cli 0.9.3 → 1.0.1

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

@@ -158,6 +158,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);
@@ -209,18 +215,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;
   }
@@ -253,124 +254,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);
@@ -388,7 +328,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.`,
@@ -396,28 +336,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 }
     );
   }
@@ -426,6 +363,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);
 }
@@ -456,14 +405,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");
@@ -479,17 +420,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 };
 }
 
@@ -512,8 +455,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)) {
@@ -522,10 +474,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)) {
@@ -555,6 +507,7 @@ async function runPackage(opts) {
   }
   return {
     ok: true,
+    command: "package",
     target,
     projectRoot: project.root,
     outputPath: result.outputPath,
@@ -598,7 +551,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),
@@ -618,7 +574,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;
@@ -632,13 +590,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)
     );