@lessonkit/cli 0.6.0 → 0.7.0

package/README.md

@@ -4,23 +4,49 @@
 [![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)
 
-LessonKit CLI (early stub).
+LessonKit CLI — scaffold, dev, build, and package learning experiences.
 
 ## Install
 
 ```bash
 npm install -g @lessonkit/cli
+# or
+npx @lessonkit/cli init my-course
 ```
 
-## Commands (0.6.0 stubs)
+**Node.js:** dev/build on Node 18+. LMS packaging targets require **Node.js 20+**.
+
+## Quick start
 
 ```bash
-lessonkit init
+lessonkit init my-course
+cd my-course
 lessonkit dev
 lessonkit build
-lessonkit package   # real dual export in 0.7.x
-lessonkit publish
+lessonkit package --target scorm12
 ```
 
-For LMS packaging today, use [`@lessonkit/lxpack`](../../packages/lxpack/README.md) or [`examples/lxpack-golden`](../../examples/lxpack-golden).
+## 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`](../../RELEASING.md) |
+
+### Package targets
+
+- `react-vite` — Vite production build → `dist/`
+- `scorm12`, `scorm2004`, `xapi`, `cmi5`, `standalone` — via `@lessonkit/lxpack`
+
+## 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.
+
+## 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

package/dist/bin.d.ts

@@ -0,0 +1 @@
+#!/usr/bin/env node

package/dist/bin.js

@@ -3,25 +3,557 @@
 // src/index.ts
 import { createRequire } from "module";
 import { Command } from "commander";
+
+// src/commands/init.ts
+import { cp, mkdir, readdir, readFile, writeFile } from "fs/promises";
+import { existsSync } from "fs";
+import { basename, dirname, join, resolve } from "path";
+import { fileURLToPath } from "url";
+
+// src/lib/errors.ts
+var EXIT_RUNTIME = 1;
+var EXIT_INVALID_PROJECT = 2;
+var EXIT_PACKAGING = 3;
+var CliError = class extends Error {
+  code;
+  exitCode;
+  issues;
+  constructor(message, opts) {
+    super(message);
+    this.name = "CliError";
+    this.code = opts.code;
+    this.exitCode = opts.exitCode;
+    this.issues = opts.issues;
+  }
+};
+function formatCliError(error) {
+  if (error instanceof CliError) {
+    const json = {
+      ok: false,
+      code: error.code,
+      message: error.message,
+      exitCode: error.exitCode,
+      issues: error.issues
+    };
+    let message2 = error.message;
+    if (error.issues?.length) {
+      const details = error.issues.map((i) => i.path ? `${i.path}: ${i.message}` : i.message).join("\n");
+      message2 = `${error.message}
+${details}`;
+    }
+    return { message: message2, exitCode: error.exitCode, json };
+  }
+  const message = error instanceof Error ? error.message : String(error);
+  return {
+    message,
+    exitCode: EXIT_RUNTIME,
+    json: { ok: false, code: "RUNTIME", message, exitCode: EXIT_RUNTIME }
+  };
+}
+
+// src/lib/exec.ts
+import { spawn } from "child_process";
+async function runCommand(command, args, opts) {
+  await new Promise((resolvePromise, rejectPromise) => {
+    const child = spawn(command, args, {
+      cwd: opts.cwd,
+      env: opts.env ?? process.env,
+      stdio: "inherit",
+      shell: false
+    });
+    child.on("error", (err) => {
+      rejectPromise(
+        new CliError(`Failed to run ${command}: ${err.message}`, {
+          code: "RUNTIME",
+          exitCode: EXIT_RUNTIME
+        })
+      );
+    });
+    child.on("close", (code) => {
+      if (code === 0) {
+        resolvePromise();
+        return;
+      }
+      rejectPromise(
+        new CliError(`${command} exited with code ${code ?? "unknown"}.`, {
+          code: "RUNTIME",
+          exitCode: EXIT_RUNTIME
+        })
+      );
+    });
+  });
+}
+async function runNpmInstall(cwd) {
+  await runCommand("npm", ["install"], { cwd });
+}
+
+// src/commands/init.ts
+var SKIP_DIRS = /* @__PURE__ */ new Set(["node_modules", "dist", ".lxpack", ".git"]);
+var SKIP_FILES = /* @__PURE__ */ new Set([".DS_Store"]);
+function getTemplateDir() {
+  const thisDir = dirname(fileURLToPath(import.meta.url));
+  return resolve(thisDir, "../../template/vite-react");
+}
+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);
+  return entries.length === 0;
+}
+async function copyTemplate(src, dest) {
+  await mkdir(dest, { recursive: true });
+  const entries = await readdir(src, { withFileTypes: true });
+  for (const entry of entries) {
+    if (SKIP_DIRS.has(entry.name) || SKIP_FILES.has(entry.name)) continue;
+    const srcPath = join(src, entry.name);
+    const destPath = join(dest, entry.name);
+    if (entry.isDirectory()) {
+      await copyTemplate(srcPath, destPath);
+    } else if (entry.isFile()) {
+      await cp(srcPath, destPath);
+    }
+  }
+}
+async function applyTemplateSubstitutions(projectDir, projectName, slug) {
+  const pkgPath = join(projectDir, "package.json");
+  const lessonkitPath = join(projectDir, "lessonkit.json");
+  const pkg = JSON.parse(await readFile(pkgPath, "utf8"));
+  pkg.name = projectName;
+  await writeFile(pkgPath, `${JSON.stringify(pkg, null, 2)}
+`, "utf8");
+  const lessonkit = JSON.parse(await readFile(lessonkitPath, "utf8"));
+  lessonkit.name = slug;
+  const course = lessonkit.course;
+  course.courseId = slug;
+  course.title = projectName;
+  await writeFile(lessonkitPath, `${JSON.stringify(lessonkit, null, 2)}
+`, "utf8");
+  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"');
+  await writeFile(appPath, appSource, "utf8");
+}
+async function runInit(opts, logger) {
+  const cwd = process.cwd();
+  const rawName = opts.name ?? (opts.here ? slugifyName(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 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
+    });
+  }
+  if (opts.here && !await isDirEmpty(projectDir) && !opts.force) {
+    throw new CliError(`Directory is not empty: ${projectDir}. Use --force to initialize anyway.`, {
+      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.`, {
+      code: "RUNTIME",
+      exitCode: EXIT_INVALID_PROJECT
+    });
+  }
+  await copyTemplate(templateDir, projectDir);
+  await applyTemplateSubstitutions(projectDir, projectName, slug);
+  if (!opts.skipInstall) {
+    if (!opts.json) logger.log(`Installing dependencies in ${projectDir}\u2026`);
+    await runNpmInstall(projectDir);
+  }
+  if (!opts.json) {
+    logger.log(`Created LessonKit project at ${projectDir}`);
+    logger.log(`Next: cd ${opts.here ? "." : slug} && lessonkit dev`);
+  }
+  return { ok: true, command: "init", projectRoot: projectDir };
+}
+
+// src/lib/project.ts
+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";
+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";
+  } catch {
+    return false;
+  }
+}
+function findProjectRoot(startDir = process.cwd()) {
+  let dir = resolve2(startDir);
+  const fsRoot = parse(dir).root;
+  while (true) {
+    const configPath = join2(dir, LESSONKIT_JSON);
+    if (existsSync2(configPath) && isProjectManifest(configPath)) {
+      return dir;
+    }
+    if (dir === fsRoot) {
+      throw new CliError(`Could not find ${LESSONKIT_JSON} in ${startDir} or any parent directory.`, {
+        code: "INVALID_PROJECT",
+        exitCode: EXIT_INVALID_PROJECT
+      });
+    }
+    dir = dirname2(dir);
+  }
+}
+async function loadLessonkitJson(projectRoot) {
+  const configPath = join2(projectRoot, LESSONKIT_JSON);
+  let raw;
+  try {
+    raw = JSON.parse(await readFile2(configPath, "utf8"));
+  } catch {
+    throw new CliError(`Failed to read or parse ${configPath}.`, {
+      code: "INVALID_PROJECT",
+      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 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
+    });
+  }
+  const courseRaw = config.course;
+  if (!courseRaw || typeof courseRaw !== "object") {
+    throw new CliError(`${configPath}: "course" must be an object.`, {
+      code: "INVALID_PROJECT",
+      exitCode: EXIT_INVALID_PROJECT
+    });
+  }
+  const validation = validateDescriptor(courseRaw);
+  if (!validation.ok) {
+    throw new CliError(`${configPath}: invalid course descriptor.`, {
+      code: "INVALID_PROJECT",
+      exitCode: EXIT_INVALID_PROJECT,
+      issues: validation.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 && typeof pathsRaw === "object") {
+    const p = pathsRaw;
+    if (typeof p.spaDistDir === "string" && p.spaDistDir.trim()) paths.spaDistDir = p.spaDistDir;
+    if (typeof p.lxpackOutDir === "string" && p.lxpackOutDir.trim()) paths.lxpackOutDir = p.lxpackOutDir;
+    if (typeof p.outputBaseDir === "string" && p.outputBaseDir.trim()) paths.outputBaseDir = p.outputBaseDir;
+  }
+  return {
+    root: projectRoot,
+    schemaVersion: 1,
+    name,
+    course: validation.descriptor,
+    paths
+  };
+}
+async function loadProject(cwd = process.cwd()) {
+  const root = findProjectRoot(cwd);
+  return loadLessonkitJson(root);
+}
+async function readPackageJson(projectRoot) {
+  const pkgPath = join2(projectRoot, PACKAGE_JSON);
+  try {
+    return JSON.parse(await readFile2(pkgPath, "utf8"));
+  } catch {
+    throw new CliError(`Failed to read or parse ${pkgPath}.`, {
+      code: "INVALID_PROJECT",
+      exitCode: EXIT_INVALID_PROJECT
+    });
+  }
+}
+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);
+  if (!vite) {
+    throw new CliError(
+      `No Vite dependency found in ${join2(projectRoot, PACKAGE_JSON)}. LessonKit projects require Vite.`,
+      { code: "INVALID_PROJECT", exitCode: EXIT_INVALID_PROJECT }
+    );
+  }
+}
+function resolveViteBin(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;
+    if (dir === fsRoot) break;
+    dir = dirname2(dir);
+  }
+  throw new CliError(
+    `Vite binary not found near ${projectRoot}. Run npm install in the project first.`,
+    { code: "INVALID_PROJECT", exitCode: EXIT_INVALID_PROJECT }
+  );
+}
+function assertNode20ForLxpack() {
+  const major = Number(process.versions.node.split(".")[0]);
+  if (major < 20) {
+    throw new CliError(
+      `LMS packaging requires Node.js 20+ (current: ${process.versions.node}). See docs/PACKAGING.md.`,
+      { code: "NODE_VERSION", exitCode: EXIT_INVALID_PROJECT }
+    );
+  }
+}
+
+// src/lib/paths.ts
+import { resolve as resolve3 } from "path";
+function resolveDistDir(project) {
+  return resolve3(project.root, project.paths.spaDistDir);
+}
+function resolveLxpackOutDir(project) {
+  return resolve3(project.root, project.paths.lxpackOutDir);
+}
+function resolvePackageOutput(project, target, override) {
+  const outputBaseDir = project.paths.outputBaseDir;
+  if (override) {
+    return { output: override, dir: target === "standalone", outputBaseDir };
+  }
+  if (target === "standalone") {
+    return { output: `${outputBaseDir}/standalone`, dir: true, outputBaseDir };
+  }
+  return { output: `${outputBaseDir}/course-${target}.zip`, dir: false, outputBaseDir };
+}
+var DEFAULT_SPA_DIST_DIR = "dist";
+function resolveViteBuildArgs(project) {
+  const args = ["build"];
+  if (project.paths.spaDistDir !== DEFAULT_SPA_DIST_DIR) {
+    args.push("--outDir", project.paths.spaDistDir);
+  }
+  return args;
+}
+var PACKAGE_TARGETS = [
+  "react-vite",
+  "scorm12",
+  "scorm2004",
+  "xapi",
+  "cmi5",
+  "standalone"
+];
+function parsePackageTarget(value) {
+  if (!value) {
+    throw new Error("TARGET_REQUIRED");
+  }
+  if (PACKAGE_TARGETS.includes(value)) {
+    return value;
+  }
+  throw new Error(`Unknown target "${value}". Valid targets: ${PACKAGE_TARGETS.join(", ")}`);
+}
+
+// src/commands/dev.ts
+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 });
+  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 buildArgs = resolveViteBuildArgs(project);
+  await runCommand(viteBin, [...buildArgs, ...opts.viteArgs ?? []], { cwd: project.root });
+  return { ok: true, command: "build", projectRoot: project.root };
+}
+
+// src/commands/package.ts
+import { existsSync as existsSync3 } from "fs";
+import { packageLessonkitCourse } from "@lessonkit/lxpack";
+async function runPackage(opts) {
+  let target;
+  try {
+    target = parsePackageTarget(opts.target);
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    if (message === "TARGET_REQUIRED") {
+      throw new CliError("--target is required. Example: lessonkit package --target scorm12", {
+        code: "TARGET_REQUIRED",
+        exitCode: EXIT_INVALID_PROJECT
+      });
+    }
+    throw new CliError(message, { code: "INVALID_PROJECT", exitCode: EXIT_INVALID_PROJECT });
+  }
+  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 (!existsSync3(distDir)) {
+      throw new CliError(`Build completed but dist directory not found at ${distDir}.`, {
+        code: "RUNTIME",
+        exitCode: EXIT_INVALID_PROJECT
+      });
+    }
+    return { ok: true, target, projectRoot: project.root, distDir };
+  }
+  assertNode20ForLxpack();
+  if (!opts.noBuild || !existsSync3(distDir)) {
+    await runBuild({ cwd: project.root, json: opts.json });
+  }
+  if (!existsSync3(distDir)) {
+    throw new CliError(`dist directory not found at ${distDir}. Run lessonkit build first.`, {
+      code: "INVALID_PROJECT",
+      exitCode: EXIT_INVALID_PROJECT
+    });
+  }
+  const outDir = resolveLxpackOutDir(project);
+  const { output, dir, outputBaseDir } = resolvePackageOutput(project, target, opts.out);
+  const result = await packageLessonkitCourse({
+    descriptor: project.course,
+    outDir,
+    spaDistDir: distDir,
+    target,
+    output,
+    dir,
+    outputBaseDir
+  });
+  if (!result.ok) {
+    throw new CliError("Packaging failed.", {
+      code: "PACKAGING",
+      exitCode: EXIT_PACKAGING,
+      issues: result.issues
+    });
+  }
+  return {
+    ok: true,
+    target,
+    projectRoot: project.root,
+    outputPath: result.outputPath,
+    outputDir: result.outputDir,
+    fileCount: result.fileCount
+  };
+}
+
+// src/lib/logger.ts
+function createLogger(opts) {
+  if (opts?.json) {
+    return {
+      log: () => {
+      },
+      error: () => {
+      }
+    };
+  }
+  return console;
+}
+
+// src/index.ts
 var require2 = createRequire(import.meta.url);
 var { version } = require2("../package.json");
-function createProgram(logger = console) {
+async function handleCommand(fn, logger, json) {
+  try {
+    const result = await fn();
+    if (json) {
+      console.log(JSON.stringify(result));
+    }
+  } catch (error) {
+    const formatted = formatCliError(error);
+    if (json) {
+      console.log(JSON.stringify(formatted.json));
+    } else {
+      logger.error(formatted.message);
+    }
+    process.exitCode = formatted.exitCode;
+  }
+}
+function createProgram(baseLogger = console) {
   const program = new Command();
   program.name("lessonkit").description("LessonKit CLI").version(version);
-  program.command("init").description("Initialize a LessonKit project (stub)").action(() => {
-    logger.log("lessonkit init (coming soon)");
-  });
-  program.command("dev").description("Run a LessonKit project in dev mode (stub)").action(() => {
-    logger.log("lessonkit dev (coming soon)");
+  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) => {
+    const logger = createLogger({ json: opts.json });
+    await handleCommand(
+      () => runInit({ name, here: opts.here, skipInstall: opts.skipInstall, force: opts.force, json: opts.json }, logger),
+      logger,
+      Boolean(opts.json)
+    );
   });
-  program.command("build").description("Build a LessonKit project (stub)").action(() => {
-    logger.log("lessonkit build (coming soon)");
+  const addCwdAndJson = (cmd) => cmd.option("--cwd <dir>", "Project root directory").option("--json", "Emit structured JSON result");
+  addCwdAndJson(
+    program.command("dev").description("Run the Vite dev server").allowUnknownOption().allowExcessArguments()
+  ).action(async (opts, command) => {
+    const logger = createLogger({ json: opts.json });
+    const viteArgs = command.args;
+    await handleCommand(
+      () => runDev({ cwd: opts.cwd, json: opts.json, viteArgs }),
+      logger,
+      Boolean(opts.json)
+    );
   });
-  program.command("package").description("Package to SCORM/xAPI formats (stub)").action(() => {
-    logger.log("lessonkit package (coming soon)");
+  addCwdAndJson(program.command("build").description("Production Vite build")).action(
+    async (opts, command) => {
+      const logger = createLogger({ json: opts.json });
+      const viteArgs = command.args;
+      await handleCommand(
+        () => runBuild({ cwd: opts.cwd, json: opts.json, viteArgs }),
+        logger,
+        Boolean(opts.json)
+      );
+    }
+  );
+  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
+      }),
+      logger,
+      Boolean(opts.json)
+    );
   });
   program.command("publish").description("Publish package artifacts (stub)").action(() => {
-    logger.log("lessonkit publish (coming soon)");
+    baseLogger.log("lessonkit publish is not implemented. See RELEASING.md for npm publish workflow.");
   });
   return program;
 }
@@ -31,4 +563,5 @@ async function run(argv = process.argv, logger = console) {
 }
 
 // src/bin.ts
-void run(process.argv);
+await run(process.argv);
+process.exit(process.exitCode ?? 0);

package/dist/index.d.ts

@@ -0,0 +1,11 @@
+import { Command } from 'commander';
+
+type CliLogger = {
+    log: (...args: unknown[]) => void;
+    error: (...args: unknown[]) => void;
+};
+
+declare function createProgram(baseLogger?: CliLogger): Command;
+declare function run(argv?: string[], logger?: CliLogger): Promise<void>;
+
+export { type CliLogger, createProgram, run };