@lessonkit/cli 0.7.0 → 0.8.1

package/README.md

@@ -1,11 +1,14 @@
 # `@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)
-[![License](https://img.shields.io/github/license/eddiethedean/lessonkit)](../../LICENSE)
+[![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)
+
 ## Install
 
 ```bash
@@ -34,7 +37,7 @@ lessonkit package --target scorm12
 | `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`](../../RELEASING.md) |
+| `lessonkit publish` | Stub — see [`RELEASING.md`](https://github.com/eddiethedean/lessonkit/blob/main/RELEASING.md) |
 
 ### Package targets
 
@@ -43,10 +46,10 @@ lessonkit package --target scorm12
 
 ## Project manifest
 
-Projects include a `lessonkit.json` at the root. See [`docs/CLI.md`](../../docs/CLI.md) for the schema, flags, exit codes, and JSON output mode.
+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.
 
 ## Related
 
-- [`docs/CLI.md`](../../docs/CLI.md) — full CLI reference
-- [`docs/PACKAGING.md`](../../docs/PACKAGING.md) — LXPack output layout
-- [`templates/vite-react`](../../templates/vite-react) — starter template
+- [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

package/dist/bin.js

@@ -102,6 +102,14 @@ async function isDirEmpty(dir) {
   const entries = await readdir(dir);
   return entries.length === 0;
 }
+async function isDirEmptyOrDotfilesOnly(dir) {
+  if (!existsSync(dir)) return true;
+  const entries = await readdir(dir);
+  return entries.every((name) => name.startsWith("."));
+}
+function escapeJsxString(value) {
+  return value.replace(/\\/g, "\\\\").replace(/"/g, '\\"');
+}
 async function copyTemplate(src, dest) {
   await mkdir(dest, { recursive: true });
   const entries = await readdir(src, { withFileTypes: true });
@@ -133,9 +141,7 @@ async function applyTemplateSubstitutions(projectDir, projectName, slug) {
   const appPath = join(projectDir, "src", "App.tsx");
   let appSource = await readFile(appPath, "utf8");
   appSource = appSource.replace(/courseId="my-course"/g, `courseId="${slug}"`);
-  appSource = appSource.replace(/title="My LessonKit Course"/g, `title="${projectName.replace(/"/g, '\\"')}"`);
-  appSource = appSource.replace(/preset="dark"/g, 'preset="default"');
-  appSource = appSource.replace(/mode="dark"/g, 'mode="light"');
+  appSource = appSource.replace(/\{\{courseTitle\}\}/g, escapeJsxString(projectName));
   await writeFile(appPath, appSource, "utf8");
 }
 async function runInit(opts, logger) {
@@ -151,10 +157,13 @@ async function runInit(opts, logger) {
   const projectName = rawName ?? slug;
   const projectDir = opts.here ? cwd : resolve(cwd, slug);
   if (!opts.here && existsSync(projectDir)) {
-    throw new CliError(`Directory already exists: ${projectDir}. Use --force to initialize anyway.`, {
-      code: "INVALID_PROJECT",
-      exitCode: EXIT_INVALID_PROJECT
-    });
+    throw new CliError(
+      `Directory already exists: ${projectDir}. Choose a different name or remove the directory.`,
+      {
+        code: "INVALID_PROJECT",
+        exitCode: EXIT_INVALID_PROJECT
+      }
+    );
   }
   if (opts.here && !await isDirEmpty(projectDir) && !opts.force) {
     throw new CliError(`Directory is not empty: ${projectDir}. Use --force to initialize anyway.`, {
@@ -162,6 +171,15 @@ async function runInit(opts, logger) {
       exitCode: EXIT_INVALID_PROJECT
     });
   }
+  if (opts.here && opts.force && !await isDirEmptyOrDotfilesOnly(projectDir)) {
+    throw new CliError(
+      `Directory is not empty: ${projectDir}. --force only initializes when the directory is empty or contains dotfiles only (e.g. .git).`,
+      {
+        code: "INVALID_PROJECT",
+        exitCode: EXIT_INVALID_PROJECT
+      }
+    );
+  }
   const templateDir = getTemplateDir();
   if (!existsSync(templateDir)) {
     throw new CliError(`Bundled template not found at ${templateDir}. Reinstall @lessonkit/cli.`, {
@@ -186,7 +204,7 @@ 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 } from "@lessonkit/lxpack";
+import { validateDescriptor, validateProjectPaths } from "@lessonkit/lxpack";
 var LESSONKIT_JSON = "lessonkit.json";
 var PACKAGE_JSON = "package.json";
 var DEFAULT_PATHS = {
@@ -283,6 +301,14 @@ async function loadLessonkitJson(projectRoot) {
     if (typeof p.lxpackOutDir === "string" && p.lxpackOutDir.trim()) paths.lxpackOutDir = p.lxpackOutDir;
     if (typeof p.outputBaseDir === "string" && p.outputBaseDir.trim()) paths.outputBaseDir = p.outputBaseDir;
   }
+  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,
@@ -344,6 +370,7 @@ function assertNode20ForLxpack() {
 
 // src/lib/paths.ts
 import { resolve as resolve3 } from "path";
+import { resolveSafePackageOutputOverride } from "@lessonkit/lxpack";
 function resolveDistDir(project) {
   return resolve3(project.root, project.paths.spaDistDir);
 }
@@ -353,7 +380,8 @@ function resolveLxpackOutDir(project) {
 function resolvePackageOutput(project, target, override) {
   const outputBaseDir = project.paths.outputBaseDir;
   if (override) {
-    return { output: override, dir: target === "standalone", outputBaseDir };
+    const resolved = resolveSafePackageOutputOverride(project.root, override);
+    return { output: resolved, dir: target === "standalone", outputBaseDir };
   }
   if (target === "standalone") {
     return { output: `${outputBaseDir}/standalone`, dir: true, outputBaseDir };
@@ -425,7 +453,9 @@ async function runPackage(opts) {
   const project = await loadProject(opts.cwd ?? process.cwd());
   const distDir = resolveDistDir(project);
   if (target === "react-vite") {
-    await runBuild({ cwd: project.root, json: opts.json });
+    if (!opts.noBuild || !existsSync3(distDir)) {
+      await runBuild({ cwd: project.root, json: opts.json });
+    }
     if (!existsSync3(distDir)) {
       throw new CliError(`Build completed but dist directory not found at ${distDir}.`, {
         code: "RUNTIME",

package/dist/index.js

@@ -100,6 +100,14 @@ async function isDirEmpty(dir) {
   const entries = await readdir(dir);
   return entries.length === 0;
 }
+async function isDirEmptyOrDotfilesOnly(dir) {
+  if (!existsSync(dir)) return true;
+  const entries = await readdir(dir);
+  return entries.every((name) => name.startsWith("."));
+}
+function escapeJsxString(value) {
+  return value.replace(/\\/g, "\\\\").replace(/"/g, '\\"');
+}
 async function copyTemplate(src, dest) {
   await mkdir(dest, { recursive: true });
   const entries = await readdir(src, { withFileTypes: true });
@@ -131,9 +139,7 @@ async function applyTemplateSubstitutions(projectDir, projectName, slug) {
   const appPath = join(projectDir, "src", "App.tsx");
   let appSource = await readFile(appPath, "utf8");
   appSource = appSource.replace(/courseId="my-course"/g, `courseId="${slug}"`);
-  appSource = appSource.replace(/title="My LessonKit Course"/g, `title="${projectName.replace(/"/g, '\\"')}"`);
-  appSource = appSource.replace(/preset="dark"/g, 'preset="default"');
-  appSource = appSource.replace(/mode="dark"/g, 'mode="light"');
+  appSource = appSource.replace(/\{\{courseTitle\}\}/g, escapeJsxString(projectName));
   await writeFile(appPath, appSource, "utf8");
 }
 async function runInit(opts, logger) {
@@ -149,10 +155,13 @@ async function runInit(opts, logger) {
   const projectName = rawName ?? slug;
   const projectDir = opts.here ? cwd : resolve(cwd, slug);
   if (!opts.here && existsSync(projectDir)) {
-    throw new CliError(`Directory already exists: ${projectDir}. Use --force to initialize anyway.`, {
-      code: "INVALID_PROJECT",
-      exitCode: EXIT_INVALID_PROJECT
-    });
+    throw new CliError(
+      `Directory already exists: ${projectDir}. Choose a different name or remove the directory.`,
+      {
+        code: "INVALID_PROJECT",
+        exitCode: EXIT_INVALID_PROJECT
+      }
+    );
   }
   if (opts.here && !await isDirEmpty(projectDir) && !opts.force) {
     throw new CliError(`Directory is not empty: ${projectDir}. Use --force to initialize anyway.`, {
@@ -160,6 +169,15 @@ async function runInit(opts, logger) {
       exitCode: EXIT_INVALID_PROJECT
     });
   }
+  if (opts.here && opts.force && !await isDirEmptyOrDotfilesOnly(projectDir)) {
+    throw new CliError(
+      `Directory is not empty: ${projectDir}. --force only initializes when the directory is empty or contains dotfiles only (e.g. .git).`,
+      {
+        code: "INVALID_PROJECT",
+        exitCode: EXIT_INVALID_PROJECT
+      }
+    );
+  }
   const templateDir = getTemplateDir();
   if (!existsSync(templateDir)) {
     throw new CliError(`Bundled template not found at ${templateDir}. Reinstall @lessonkit/cli.`, {
@@ -184,7 +202,7 @@ 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 } from "@lessonkit/lxpack";
+import { validateDescriptor, validateProjectPaths } from "@lessonkit/lxpack";
 var LESSONKIT_JSON = "lessonkit.json";
 var PACKAGE_JSON = "package.json";
 var DEFAULT_PATHS = {
@@ -281,6 +299,14 @@ async function loadLessonkitJson(projectRoot) {
     if (typeof p.lxpackOutDir === "string" && p.lxpackOutDir.trim()) paths.lxpackOutDir = p.lxpackOutDir;
     if (typeof p.outputBaseDir === "string" && p.outputBaseDir.trim()) paths.outputBaseDir = p.outputBaseDir;
   }
+  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,
@@ -342,6 +368,7 @@ function assertNode20ForLxpack() {
 
 // src/lib/paths.ts
 import { resolve as resolve3 } from "path";
+import { resolveSafePackageOutputOverride } from "@lessonkit/lxpack";
 function resolveDistDir(project) {
   return resolve3(project.root, project.paths.spaDistDir);
 }
@@ -351,7 +378,8 @@ function resolveLxpackOutDir(project) {
 function resolvePackageOutput(project, target, override) {
   const outputBaseDir = project.paths.outputBaseDir;
   if (override) {
-    return { output: override, dir: target === "standalone", outputBaseDir };
+    const resolved = resolveSafePackageOutputOverride(project.root, override);
+    return { output: resolved, dir: target === "standalone", outputBaseDir };
   }
   if (target === "standalone") {
     return { output: `${outputBaseDir}/standalone`, dir: true, outputBaseDir };
@@ -423,7 +451,9 @@ async function runPackage(opts) {
   const project = await loadProject(opts.cwd ?? process.cwd());
   const distDir = resolveDistDir(project);
   if (target === "react-vite") {
-    await runBuild({ cwd: project.root, json: opts.json });
+    if (!opts.noBuild || !existsSync3(distDir)) {
+      await runBuild({ cwd: project.root, json: opts.json });
+    }
     if (!existsSync3(distDir)) {
       throw new CliError(`Build completed but dist directory not found at ${distDir}.`, {
         code: "RUNTIME",

package/package.json

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

package/template/vite-react/README.md

@@ -1,9 +1,9 @@
 # LessonKit Vite + React template
 
-[![CI](https://github.com/eddiethedean/lessonkit/actions/workflows/ci.yml/badge.svg)](https://github.com/eddiethedean/lessonkit/actions/workflows/ci.yml)
-[![License](https://img.shields.io/github/license/eddiethedean/lessonkit)](../../LICENSE)
+[![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)
 
-This is a starter template used by `lessonkit init`. See [`docs/CLI.md`](../../docs/CLI.md).
+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
 
@@ -14,6 +14,6 @@ npm run dev
 
 ## Notes
 
-- This template depends on `@lessonkit/react`.
-- It’s copied by `@lessonkit/cli` when you run `lessonkit init`.
-
+- 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).