@lessonkit/cli 1.5.0 → 1.6.0

package/dist/bin.js

@@ -1,12 +1,12 @@
 #!/usr/bin/env node
 
 // src/index.ts
-import { createRequire as createRequire2 } from "module";
+import { createRequire as createRequire3 } from "module";
 import { Command } from "commander";
 
 // src/commands/init.ts
 import { slugifyId } from "@lessonkit/core";
-import { cp, mkdir, readdir, readFile, rename, rm, writeFile } from "fs/promises";
+import { cp, mkdir, readdir, readFile, rename, rm, stat, writeFile } from "fs/promises";
 import { existsSync } from "fs";
 import { randomUUID } from "crypto";
 import { basename, dirname, join, resolve } from "path";
@@ -138,6 +138,11 @@ function getTemplateDir() {
   }
   return candidates[0];
 }
+async function isDirEmpty(dir) {
+  if (!existsSync(dir)) return true;
+  const entries = await readdir(dir);
+  return entries.length === 0;
+}
 async function isDirEmptyOrDotfilesOnly(dir) {
   if (!existsSync(dir)) return true;
   const entries = await readdir(dir);
@@ -190,6 +195,51 @@ async function applyTemplateSubstitutions(projectDir, projectName, slug) {
   appSource = appSource.replace(/\{\{courseTitle\}\}/g, escapeJsxString(projectName));
   await writeFile(appPath, appSource, "utf8");
 }
+async function backupConflictingFiles(stagingDir, projectDir) {
+  const backups = /* @__PURE__ */ new Map();
+  const stagingEntries = await readdir(stagingDir, { withFileTypes: true });
+  for (const entry of stagingEntries) {
+    const destPath = join(projectDir, entry.name);
+    if (!existsSync(destPath)) continue;
+    const destStat = await stat(destPath);
+    if (destStat.isFile()) {
+      backups.set(entry.name, await readFile(destPath));
+    }
+  }
+  return backups;
+}
+async function rollbackPromotedFiles(projectDir, stagingDir, preExisting, backups) {
+  const failures = [];
+  let stagingEntries;
+  try {
+    stagingEntries = await readdir(stagingDir, { withFileTypes: true });
+  } catch {
+    return;
+  }
+  for (const entry of stagingEntries) {
+    if (preExisting.has(entry.name)) continue;
+    try {
+      await rm(join(projectDir, entry.name), { recursive: true, force: true });
+    } catch (err) {
+      failures.push(
+        `remove ${entry.name}: ${err instanceof Error ? err.message : String(err)}`
+      );
+    }
+  }
+  for (const [name, content] of backups) {
+    try {
+      await writeFile(join(projectDir, name), content);
+    } catch (err) {
+      failures.push(`restore ${name}: ${err instanceof Error ? err.message : String(err)}`);
+    }
+  }
+  if (failures.length > 0) {
+    throw new CliError(`Init rollback failed: ${failures.join("; ")}`, {
+      code: "RUNTIME",
+      exitCode: EXIT_INVALID_PROJECT
+    });
+  }
+}
 async function promoteStagingToProjectDir(stagingDir, projectDir) {
   await mkdir(projectDir, { recursive: true });
   const entries = await readdir(stagingDir, { withFileTypes: true });
@@ -204,6 +254,16 @@ async function promoteStagingToProjectDir(stagingDir, projectDir) {
     }
   }
 }
+var __testInitHelpers = {
+  getTemplateDir,
+  isDirEmpty,
+  isDirEmptyOrDotfilesOnly,
+  escapeJsxString,
+  copyTemplate,
+  promoteStagingToProjectDir,
+  rollbackPromotedFiles,
+  backupConflictingFiles
+};
 async function runInit(opts, logger) {
   const cwd = process.cwd();
   const rawName = opts.name ?? (opts.here ? slugifyId(basename(process.cwd()) || "my-course") : void 0);
@@ -232,10 +292,13 @@ async function runInit(opts, logger) {
     );
   }
   if (opts.here && !await isDirEmptyOrDotfilesOnly(projectDir) && !opts.force) {
-    throw new CliError(`Directory is not empty: ${projectDir}. Use --force to initialize anyway.`, {
-      code: "INVALID_PROJECT",
-      exitCode: EXIT_INVALID_PROJECT
-    });
+    throw new CliError(
+      `Directory is not empty: ${projectDir}. Use --here --force only when the directory is empty or contains dotfiles only (e.g. .git).`,
+      {
+        code: "INVALID_PROJECT",
+        exitCode: EXIT_INVALID_PROJECT
+      }
+    );
   }
   if (opts.here && opts.force && !await isDirEmptyOrDotfilesOnly(projectDir)) {
     throw new CliError(
@@ -262,7 +325,23 @@ async function runInit(opts, logger) {
       await runNpmInstall(stagingDir);
     }
     if (opts.here) {
-      await promoteStagingToProjectDir(stagingDir, projectDir);
+      const preExisting = new Set(await readdir(projectDir));
+      const backups = await backupConflictingFiles(stagingDir, projectDir);
+      try {
+        await __testInitHelpers.promoteStagingToProjectDir(stagingDir, projectDir);
+      } catch (promoteErr) {
+        try {
+          await rollbackPromotedFiles(projectDir, stagingDir, preExisting, backups);
+        } catch (rollbackErr) {
+          const promoteMessage = promoteErr instanceof Error ? promoteErr.message : String(promoteErr);
+          const rollbackMessage = rollbackErr instanceof Error ? rollbackErr.message : String(rollbackErr);
+          throw new CliError(`${promoteMessage}; ${rollbackMessage}`, {
+            code: "RUNTIME",
+            exitCode: EXIT_INVALID_PROJECT
+          });
+        }
+        throw promoteErr;
+      }
       await rm(stagingDir, { recursive: true, force: true });
     } else {
       await rename(stagingDir, projectDir);
@@ -283,7 +362,9 @@ async function runInit(opts, logger) {
 
 // src/commands/dev.ts
 import { existsSync as existsSync3 } from "fs";
-import { join as join3 } from "path";
+import { mkdir as mkdir2 } from "fs/promises";
+import { dirname as dirname3, join as join3 } from "path";
+import { assertSpaDistContentsSafe } from "@lessonkit/lxpack";
 
 // src/lib/project.ts
 import { readFileSync, existsSync as existsSync2 } from "fs";
@@ -293,10 +374,13 @@ import { dirname as dirname2, join as join2, parse, resolve as resolve2 } from "
 import { parseLessonkitManifest } from "@lessonkit/lxpack";
 var LESSONKIT_JSON = "lessonkit.json";
 var PACKAGE_JSON = "package.json";
+function isSchemaVersionOne(value) {
+  return value === 1 || value === "1";
+}
 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" && !Array.isArray(raw.course);
+    return isSchemaVersionOne(raw.schemaVersion) && typeof raw.name === "string" && raw.course !== null && typeof raw.course === "object" && !Array.isArray(raw.course);
   } catch {
     return false;
   }
@@ -469,7 +553,12 @@ function resolvePackageOutput(project, target, override) {
   if (override) {
     try {
       const resolved = resolveSafePackageOutputOverride(project.root, override);
-      return { output: resolved, dir: target === "standalone", outputBaseDir };
+      const isZipOutput = override.trim().toLowerCase().endsWith(".zip");
+      return {
+        output: resolved,
+        dir: target === "standalone" && !isZipOutput,
+        outputBaseDir
+      };
     } catch (err) {
       const message = err instanceof Error ? err.message : String(err);
       throw new CliError(message, { code: "INVALID_PROJECT", exitCode: EXIT_INVALID_PROJECT });
@@ -515,7 +604,8 @@ async function runDev(opts) {
   const pkg = await readPackageJson(project.root);
   assertViteProject(pkg, project.root);
   const viteJs = resolveViteJs(project.root);
-  await runCommand(process.execPath, [viteJs, ...opts.viteArgs ?? []], {
+  const devArgs = stripOutDirFromViteArgs(opts.viteArgs ?? []);
+  await runCommand(process.execPath, [viteJs, ...devArgs], {
     cwd: project.root,
     timeoutMs: 0
   });
@@ -526,11 +616,15 @@ async function runBuild(opts) {
   const pkg = await readPackageJson(project.root);
   assertViteProject(pkg, project.root);
   const viteJs = resolveViteJs(project.root);
+  const distDir = resolveDistDir(project);
+  await mkdir2(dirname3(distDir), { recursive: true });
+  if (existsSync3(distDir)) {
+    await assertSpaDistContentsSafe({ main: distDir }, project.root);
+  }
   const buildArgs = resolveViteBuildArgv(project, opts.viteArgs);
   await runCommand(process.execPath, [viteJs, ...buildArgs], {
     cwd: project.root
   });
-  const distDir = resolveDistDir(project);
   const indexHtml = join3(distDir, "index.html");
   if (!existsSync3(indexHtml)) {
     throw new CliError(
@@ -609,7 +703,8 @@ async function runPackage(opts) {
     output,
     dir,
     outputBaseDir,
-    strictParity: opts.strictParity
+    strictParity: opts.strictParity,
+    strictBuild: opts.strict
   });
   if (!result.ok) {
     throw new CliError("Packaging failed.", {
@@ -641,6 +736,112 @@ async function runPackage(opts) {
   };
 }
 
+// src/commands/export.ts
+import { existsSync as existsSync5 } from "fs";
+import { relative, resolve as resolve4 } from "path";
+import { exportLkcourse, resolveSafePackageOutputOverride as resolveSafePackageOutputOverride2 } from "@lessonkit/lxpack";
+function resolveExportOutput(projectRoot, override, defaultName) {
+  if (override) {
+    try {
+      return resolveSafePackageOutputOverride2(projectRoot, override);
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      throw new CliError(message, { code: "INVALID_PROJECT", exitCode: EXIT_INVALID_PROJECT });
+    }
+  }
+  return resolve4(projectRoot, `${defaultName ?? "course"}.lkcourse`);
+}
+async function runExport(opts) {
+  const project = await loadProject(opts.cwd ?? process.cwd());
+  const distDir = resolve4(project.root, project.paths.spaDistDir);
+  if (opts.noBuild && !existsSync5(distDir)) {
+    throw new CliError(
+      `dist directory not found at ${distDir}. Run lessonkit build before export with --no-build.`,
+      {
+        code: "INVALID_PROJECT",
+        exitCode: EXIT_INVALID_PROJECT
+      }
+    );
+  }
+  if (!opts.noBuild) {
+    await runBuild({ cwd: project.root, json: opts.json });
+  }
+  if (!existsSync5(distDir)) {
+    throw new CliError(`dist directory not found at ${distDir}. Run lessonkit build first.`, {
+      code: "INVALID_PROJECT",
+      exitCode: EXIT_INVALID_PROJECT
+    });
+  }
+  const resolvedOut = resolveExportOutput(project.root, opts.out, project.name);
+  const outRelative = relative(project.root, resolvedOut).replace(/\\/g, "/");
+  const result = await exportLkcourse({
+    projectRoot: project.root,
+    manifest: project,
+    outPath: outRelative,
+    includeBlockTree: Boolean(opts.withBlockTree)
+  });
+  if (!result.ok) {
+    throw new CliError(
+      result.issues.map((i) => `${i.path}: ${i.message}`).join("; "),
+      { code: "EXPORT_FAILED", exitCode: EXIT_PACKAGING }
+    );
+  }
+  return {
+    ok: true,
+    command: "export",
+    projectRoot: project.root,
+    archivePath: result.archivePath,
+    fileCount: result.fileCount,
+    includeBlockTree: result.includeBlockTree
+  };
+}
+
+// src/commands/blocks.ts
+import { readFileSync as readFileSync2 } from "fs";
+import { createRequire as createRequire2 } from "module";
+function loadBlockCatalog() {
+  const require3 = createRequire2(import.meta.url);
+  const catalogPath = require3.resolve("@lessonkit/react/block-catalog.v3.json");
+  return JSON.parse(readFileSync2(catalogPath, "utf8"));
+}
+function filterEntries(entries, opts) {
+  return entries.filter((entry) => {
+    if (opts.category && entry.category !== opts.category) return false;
+    if (opts.tier && entry.tier !== opts.tier) return false;
+    return true;
+  });
+}
+async function runBlocksList(opts) {
+  const catalog = loadBlockCatalog();
+  const entries = filterEntries(catalog.entries, opts);
+  if (!opts.json) {
+    const lines = [
+      "type	category	h5pMachineName",
+      ...entries.map(
+        (entry) => [
+          entry.type,
+          entry.category ?? "\u2014",
+          entry.h5pMachineName ?? "\u2014"
+        ].join("	")
+      )
+    ];
+    return {
+      ok: true,
+      command: "blocks list",
+      schemaVersion: catalog.schemaVersion,
+      count: entries.length,
+      text: lines.join("\n")
+    };
+  }
+  return {
+    ok: true,
+    command: "blocks list",
+    schemaVersion: catalog.schemaVersion,
+    count: entries.length,
+    entries
+  };
+}
+
 // src/lib/logger.ts
 function createLogger(opts) {
   if (opts?.json) {
@@ -655,7 +856,7 @@ function createLogger(opts) {
 }
 
 // src/index.ts
-var require2 = createRequire2(import.meta.url);
+var require2 = createRequire3(import.meta.url);
 var { version } = require2("../package.json");
 async function handleCommand(fn, logger, json) {
   try {
@@ -712,7 +913,7 @@ 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("--strict-parity", "Treat React ID parity warnings as packaging errors").option("--json", "Emit structured JSON result").action(async (opts) => {
+  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("--strict-parity", "Treat React ID parity warnings as packaging errors").option("--strict", "Treat Vite build warnings as packaging failures").option("--json", "Emit structured JSON result").action(async (opts) => {
     const logger = createLogger({ json: opts.json });
     await handleCommand(
       async () => {
@@ -722,7 +923,8 @@ function createProgram(baseLogger = console) {
           noBuild: opts.build === false,
           out: opts.out,
           json: opts.json,
-          strictParity: opts.strictParity
+          strictParity: opts.strictParity,
+          strict: opts.strict
         });
         if (!opts.json && result.ok && result.command === "package") {
           if (result.target === "react-vite") {
@@ -740,6 +942,46 @@ function createProgram(baseLogger = console) {
       Boolean(opts.json)
     );
   });
+  addCwdAndJson(
+    program.command("export").description("Export a portable .lkcourse archive (manifest + interchange + dist)").option("--out <path>", "Output .lkcourse path (relative to project root)").option("--no-build", "Skip implicit Vite build").option("--with-block-tree", "Include optional block-tree.json from src scan")
+  ).action(async (opts) => {
+    const logger = createLogger({ json: opts.json });
+    await handleCommand(
+      async () => {
+        const result = await runExport({
+          cwd: opts.cwd,
+          out: opts.out,
+          noBuild: opts.build === false,
+          withBlockTree: opts.withBlockTree,
+          json: opts.json
+        });
+        if (!opts.json && result.ok && result.command === "export") {
+          logger.log(`Exported .lkcourse \u2192 ${result.archivePath} (${result.fileCount} files)`);
+        }
+        return result;
+      },
+      logger,
+      Boolean(opts.json)
+    );
+  });
+  program.command("blocks").description("Block registry commands").command("list").description("List runtime blocks from block-catalog.v3.json").option("--json", "Emit structured JSON result").option("--category <category>", "Filter by category (container, assessment, content, compound)").option("--tier <tier>", "Filter by tier (A, B, C, D, E)").action(async (opts) => {
+    const logger = createLogger({ json: opts.json });
+    await handleCommand(
+      async () => {
+        const result = await runBlocksList({
+          json: opts.json,
+          category: opts.category,
+          tier: opts.tier
+        });
+        if (!opts.json && result.ok && "text" in result && typeof result.text === "string") {
+          logger.log(result.text);
+        }
+        return result;
+      },
+      logger,
+      Boolean(opts.json)
+    );
+  });
   program.command("publish").description("[maintainers] Not implemented \u2014 use Changesets (see RELEASING.md)").action(() => {
     baseLogger.log(
       "lessonkit publish is not implemented. Monorepo releases use Changesets: npm run changeset && npm run version-packages && npm run release. See RELEASING.md."

package/dist/index.js

@@ -1,10 +1,10 @@
 // src/index.ts
-import { createRequire as createRequire2 } from "module";
+import { createRequire as createRequire3 } from "module";
 import { Command } from "commander";
 
 // src/commands/init.ts
 import { slugifyId } from "@lessonkit/core";
-import { cp, mkdir, readdir, readFile, rename, rm, writeFile } from "fs/promises";
+import { cp, mkdir, readdir, readFile, rename, rm, stat, writeFile } from "fs/promises";
 import { existsSync } from "fs";
 import { randomUUID } from "crypto";
 import { basename, dirname, join, resolve } from "path";
@@ -136,6 +136,11 @@ function getTemplateDir() {
   }
   return candidates[0];
 }
+async function isDirEmpty(dir) {
+  if (!existsSync(dir)) return true;
+  const entries = await readdir(dir);
+  return entries.length === 0;
+}
 async function isDirEmptyOrDotfilesOnly(dir) {
   if (!existsSync(dir)) return true;
   const entries = await readdir(dir);
@@ -188,6 +193,51 @@ async function applyTemplateSubstitutions(projectDir, projectName, slug) {
   appSource = appSource.replace(/\{\{courseTitle\}\}/g, escapeJsxString(projectName));
   await writeFile(appPath, appSource, "utf8");
 }
+async function backupConflictingFiles(stagingDir, projectDir) {
+  const backups = /* @__PURE__ */ new Map();
+  const stagingEntries = await readdir(stagingDir, { withFileTypes: true });
+  for (const entry of stagingEntries) {
+    const destPath = join(projectDir, entry.name);
+    if (!existsSync(destPath)) continue;
+    const destStat = await stat(destPath);
+    if (destStat.isFile()) {
+      backups.set(entry.name, await readFile(destPath));
+    }
+  }
+  return backups;
+}
+async function rollbackPromotedFiles(projectDir, stagingDir, preExisting, backups) {
+  const failures = [];
+  let stagingEntries;
+  try {
+    stagingEntries = await readdir(stagingDir, { withFileTypes: true });
+  } catch {
+    return;
+  }
+  for (const entry of stagingEntries) {
+    if (preExisting.has(entry.name)) continue;
+    try {
+      await rm(join(projectDir, entry.name), { recursive: true, force: true });
+    } catch (err) {
+      failures.push(
+        `remove ${entry.name}: ${err instanceof Error ? err.message : String(err)}`
+      );
+    }
+  }
+  for (const [name, content] of backups) {
+    try {
+      await writeFile(join(projectDir, name), content);
+    } catch (err) {
+      failures.push(`restore ${name}: ${err instanceof Error ? err.message : String(err)}`);
+    }
+  }
+  if (failures.length > 0) {
+    throw new CliError(`Init rollback failed: ${failures.join("; ")}`, {
+      code: "RUNTIME",
+      exitCode: EXIT_INVALID_PROJECT
+    });
+  }
+}
 async function promoteStagingToProjectDir(stagingDir, projectDir) {
   await mkdir(projectDir, { recursive: true });
   const entries = await readdir(stagingDir, { withFileTypes: true });
@@ -202,6 +252,16 @@ async function promoteStagingToProjectDir(stagingDir, projectDir) {
     }
   }
 }
+var __testInitHelpers = {
+  getTemplateDir,
+  isDirEmpty,
+  isDirEmptyOrDotfilesOnly,
+  escapeJsxString,
+  copyTemplate,
+  promoteStagingToProjectDir,
+  rollbackPromotedFiles,
+  backupConflictingFiles
+};
 async function runInit(opts, logger) {
   const cwd = process.cwd();
   const rawName = opts.name ?? (opts.here ? slugifyId(basename(process.cwd()) || "my-course") : void 0);
@@ -230,10 +290,13 @@ async function runInit(opts, logger) {
     );
   }
   if (opts.here && !await isDirEmptyOrDotfilesOnly(projectDir) && !opts.force) {
-    throw new CliError(`Directory is not empty: ${projectDir}. Use --force to initialize anyway.`, {
-      code: "INVALID_PROJECT",
-      exitCode: EXIT_INVALID_PROJECT
-    });
+    throw new CliError(
+      `Directory is not empty: ${projectDir}. Use --here --force only when the directory is empty or contains dotfiles only (e.g. .git).`,
+      {
+        code: "INVALID_PROJECT",
+        exitCode: EXIT_INVALID_PROJECT
+      }
+    );
   }
   if (opts.here && opts.force && !await isDirEmptyOrDotfilesOnly(projectDir)) {
     throw new CliError(
@@ -260,7 +323,23 @@ async function runInit(opts, logger) {
       await runNpmInstall(stagingDir);
     }
     if (opts.here) {
-      await promoteStagingToProjectDir(stagingDir, projectDir);
+      const preExisting = new Set(await readdir(projectDir));
+      const backups = await backupConflictingFiles(stagingDir, projectDir);
+      try {
+        await __testInitHelpers.promoteStagingToProjectDir(stagingDir, projectDir);
+      } catch (promoteErr) {
+        try {
+          await rollbackPromotedFiles(projectDir, stagingDir, preExisting, backups);
+        } catch (rollbackErr) {
+          const promoteMessage = promoteErr instanceof Error ? promoteErr.message : String(promoteErr);
+          const rollbackMessage = rollbackErr instanceof Error ? rollbackErr.message : String(rollbackErr);
+          throw new CliError(`${promoteMessage}; ${rollbackMessage}`, {
+            code: "RUNTIME",
+            exitCode: EXIT_INVALID_PROJECT
+          });
+        }
+        throw promoteErr;
+      }
       await rm(stagingDir, { recursive: true, force: true });
     } else {
       await rename(stagingDir, projectDir);
@@ -281,7 +360,9 @@ async function runInit(opts, logger) {
 
 // src/commands/dev.ts
 import { existsSync as existsSync3 } from "fs";
-import { join as join3 } from "path";
+import { mkdir as mkdir2 } from "fs/promises";
+import { dirname as dirname3, join as join3 } from "path";
+import { assertSpaDistContentsSafe } from "@lessonkit/lxpack";
 
 // src/lib/project.ts
 import { readFileSync, existsSync as existsSync2 } from "fs";
@@ -291,10 +372,13 @@ import { dirname as dirname2, join as join2, parse, resolve as resolve2 } from "
 import { parseLessonkitManifest } from "@lessonkit/lxpack";
 var LESSONKIT_JSON = "lessonkit.json";
 var PACKAGE_JSON = "package.json";
+function isSchemaVersionOne(value) {
+  return value === 1 || value === "1";
+}
 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" && !Array.isArray(raw.course);
+    return isSchemaVersionOne(raw.schemaVersion) && typeof raw.name === "string" && raw.course !== null && typeof raw.course === "object" && !Array.isArray(raw.course);
   } catch {
     return false;
   }
@@ -467,7 +551,12 @@ function resolvePackageOutput(project, target, override) {
   if (override) {
     try {
       const resolved = resolveSafePackageOutputOverride(project.root, override);
-      return { output: resolved, dir: target === "standalone", outputBaseDir };
+      const isZipOutput = override.trim().toLowerCase().endsWith(".zip");
+      return {
+        output: resolved,
+        dir: target === "standalone" && !isZipOutput,
+        outputBaseDir
+      };
     } catch (err) {
       const message = err instanceof Error ? err.message : String(err);
       throw new CliError(message, { code: "INVALID_PROJECT", exitCode: EXIT_INVALID_PROJECT });
@@ -513,7 +602,8 @@ async function runDev(opts) {
   const pkg = await readPackageJson(project.root);
   assertViteProject(pkg, project.root);
   const viteJs = resolveViteJs(project.root);
-  await runCommand(process.execPath, [viteJs, ...opts.viteArgs ?? []], {
+  const devArgs = stripOutDirFromViteArgs(opts.viteArgs ?? []);
+  await runCommand(process.execPath, [viteJs, ...devArgs], {
     cwd: project.root,
     timeoutMs: 0
   });
@@ -524,11 +614,15 @@ async function runBuild(opts) {
   const pkg = await readPackageJson(project.root);
   assertViteProject(pkg, project.root);
   const viteJs = resolveViteJs(project.root);
+  const distDir = resolveDistDir(project);
+  await mkdir2(dirname3(distDir), { recursive: true });
+  if (existsSync3(distDir)) {
+    await assertSpaDistContentsSafe({ main: distDir }, project.root);
+  }
   const buildArgs = resolveViteBuildArgv(project, opts.viteArgs);
   await runCommand(process.execPath, [viteJs, ...buildArgs], {
     cwd: project.root
   });
-  const distDir = resolveDistDir(project);
   const indexHtml = join3(distDir, "index.html");
   if (!existsSync3(indexHtml)) {
     throw new CliError(
@@ -607,7 +701,8 @@ async function runPackage(opts) {
     output,
     dir,
     outputBaseDir,
-    strictParity: opts.strictParity
+    strictParity: opts.strictParity,
+    strictBuild: opts.strict
   });
   if (!result.ok) {
     throw new CliError("Packaging failed.", {
@@ -639,6 +734,112 @@ async function runPackage(opts) {
   };
 }
 
+// src/commands/export.ts
+import { existsSync as existsSync5 } from "fs";
+import { relative, resolve as resolve4 } from "path";
+import { exportLkcourse, resolveSafePackageOutputOverride as resolveSafePackageOutputOverride2 } from "@lessonkit/lxpack";
+function resolveExportOutput(projectRoot, override, defaultName) {
+  if (override) {
+    try {
+      return resolveSafePackageOutputOverride2(projectRoot, override);
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      throw new CliError(message, { code: "INVALID_PROJECT", exitCode: EXIT_INVALID_PROJECT });
+    }
+  }
+  return resolve4(projectRoot, `${defaultName ?? "course"}.lkcourse`);
+}
+async function runExport(opts) {
+  const project = await loadProject(opts.cwd ?? process.cwd());
+  const distDir = resolve4(project.root, project.paths.spaDistDir);
+  if (opts.noBuild && !existsSync5(distDir)) {
+    throw new CliError(
+      `dist directory not found at ${distDir}. Run lessonkit build before export with --no-build.`,
+      {
+        code: "INVALID_PROJECT",
+        exitCode: EXIT_INVALID_PROJECT
+      }
+    );
+  }
+  if (!opts.noBuild) {
+    await runBuild({ cwd: project.root, json: opts.json });
+  }
+  if (!existsSync5(distDir)) {
+    throw new CliError(`dist directory not found at ${distDir}. Run lessonkit build first.`, {
+      code: "INVALID_PROJECT",
+      exitCode: EXIT_INVALID_PROJECT
+    });
+  }
+  const resolvedOut = resolveExportOutput(project.root, opts.out, project.name);
+  const outRelative = relative(project.root, resolvedOut).replace(/\\/g, "/");
+  const result = await exportLkcourse({
+    projectRoot: project.root,
+    manifest: project,
+    outPath: outRelative,
+    includeBlockTree: Boolean(opts.withBlockTree)
+  });
+  if (!result.ok) {
+    throw new CliError(
+      result.issues.map((i) => `${i.path}: ${i.message}`).join("; "),
+      { code: "EXPORT_FAILED", exitCode: EXIT_PACKAGING }
+    );
+  }
+  return {
+    ok: true,
+    command: "export",
+    projectRoot: project.root,
+    archivePath: result.archivePath,
+    fileCount: result.fileCount,
+    includeBlockTree: result.includeBlockTree
+  };
+}
+
+// src/commands/blocks.ts
+import { readFileSync as readFileSync2 } from "fs";
+import { createRequire as createRequire2 } from "module";
+function loadBlockCatalog() {
+  const require3 = createRequire2(import.meta.url);
+  const catalogPath = require3.resolve("@lessonkit/react/block-catalog.v3.json");
+  return JSON.parse(readFileSync2(catalogPath, "utf8"));
+}
+function filterEntries(entries, opts) {
+  return entries.filter((entry) => {
+    if (opts.category && entry.category !== opts.category) return false;
+    if (opts.tier && entry.tier !== opts.tier) return false;
+    return true;
+  });
+}
+async function runBlocksList(opts) {
+  const catalog = loadBlockCatalog();
+  const entries = filterEntries(catalog.entries, opts);
+  if (!opts.json) {
+    const lines = [
+      "type	category	h5pMachineName",
+      ...entries.map(
+        (entry) => [
+          entry.type,
+          entry.category ?? "\u2014",
+          entry.h5pMachineName ?? "\u2014"
+        ].join("	")
+      )
+    ];
+    return {
+      ok: true,
+      command: "blocks list",
+      schemaVersion: catalog.schemaVersion,
+      count: entries.length,
+      text: lines.join("\n")
+    };
+  }
+  return {
+    ok: true,
+    command: "blocks list",
+    schemaVersion: catalog.schemaVersion,
+    count: entries.length,
+    entries
+  };
+}
+
 // src/lib/logger.ts
 function createLogger(opts) {
   if (opts?.json) {
@@ -653,7 +854,7 @@ function createLogger(opts) {
 }
 
 // src/index.ts
-var require2 = createRequire2(import.meta.url);
+var require2 = createRequire3(import.meta.url);
 var { version } = require2("../package.json");
 async function handleCommand(fn, logger, json) {
   try {
@@ -710,7 +911,7 @@ 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("--strict-parity", "Treat React ID parity warnings as packaging errors").option("--json", "Emit structured JSON result").action(async (opts) => {
+  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("--strict-parity", "Treat React ID parity warnings as packaging errors").option("--strict", "Treat Vite build warnings as packaging failures").option("--json", "Emit structured JSON result").action(async (opts) => {
     const logger = createLogger({ json: opts.json });
     await handleCommand(
       async () => {
@@ -720,7 +921,8 @@ function createProgram(baseLogger = console) {
           noBuild: opts.build === false,
           out: opts.out,
           json: opts.json,
-          strictParity: opts.strictParity
+          strictParity: opts.strictParity,
+          strict: opts.strict
         });
         if (!opts.json && result.ok && result.command === "package") {
           if (result.target === "react-vite") {
@@ -738,6 +940,46 @@ function createProgram(baseLogger = console) {
       Boolean(opts.json)
     );
   });
+  addCwdAndJson(
+    program.command("export").description("Export a portable .lkcourse archive (manifest + interchange + dist)").option("--out <path>", "Output .lkcourse path (relative to project root)").option("--no-build", "Skip implicit Vite build").option("--with-block-tree", "Include optional block-tree.json from src scan")
+  ).action(async (opts) => {
+    const logger = createLogger({ json: opts.json });
+    await handleCommand(
+      async () => {
+        const result = await runExport({
+          cwd: opts.cwd,
+          out: opts.out,
+          noBuild: opts.build === false,
+          withBlockTree: opts.withBlockTree,
+          json: opts.json
+        });
+        if (!opts.json && result.ok && result.command === "export") {
+          logger.log(`Exported .lkcourse \u2192 ${result.archivePath} (${result.fileCount} files)`);
+        }
+        return result;
+      },
+      logger,
+      Boolean(opts.json)
+    );
+  });
+  program.command("blocks").description("Block registry commands").command("list").description("List runtime blocks from block-catalog.v3.json").option("--json", "Emit structured JSON result").option("--category <category>", "Filter by category (container, assessment, content, compound)").option("--tier <tier>", "Filter by tier (A, B, C, D, E)").action(async (opts) => {
+    const logger = createLogger({ json: opts.json });
+    await handleCommand(
+      async () => {
+        const result = await runBlocksList({
+          json: opts.json,
+          category: opts.category,
+          tier: opts.tier
+        });
+        if (!opts.json && result.ok && "text" in result && typeof result.text === "string") {
+          logger.log(result.text);
+        }
+        return result;
+      },
+      logger,
+      Boolean(opts.json)
+    );
+  });
   program.command("publish").description("[maintainers] Not implemented \u2014 use Changesets (see RELEASING.md)").action(() => {
     baseLogger.log(
       "lessonkit publish is not implemented. Monorepo releases use Changesets: npm run changeset && npm run version-packages && npm run release. See RELEASING.md."

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lessonkit/cli",
-  "version": "1.5.0",
+  "version": "1.6.0",
   "private": false,
   "description": "LessonKit CLI — init, dev, build, and package learning experiences.",
   "license": "Apache-2.0",
@@ -45,8 +45,9 @@
     "lint": "eslint --max-warnings 0 \"src/**/*.{ts,tsx}\" \"test/**/*.{ts,tsx}\""
   },
   "dependencies": {
-    "@lessonkit/core": "1.5.0",
-    "@lessonkit/lxpack": "1.5.0",
+    "@lessonkit/core": "1.6.0",
+    "@lessonkit/lxpack": "1.6.0",
+    "@lessonkit/react": "1.6.0",
     "commander": "^15.0.0"
   },
   "engines": {

package/template/vite-react/package.json

@@ -16,16 +16,16 @@
     "test:coverage": "vitest run --coverage --passWithNoTests=false"
   },
   "dependencies": {
-    "@lessonkit/core": "^1.5.0",
-    "@lessonkit/react": "^1.5.0",
-    "@lessonkit/themes": "^1.5.0",
-    "@lessonkit/xapi": "^1.5.0",
+    "@lessonkit/core": "^1.6.0",
+    "@lessonkit/react": "^1.6.0",
+    "@lessonkit/themes": "^1.6.0",
+    "@lessonkit/xapi": "^1.6.0",
     "react": "^19.2.7",
     "react-dom": "^19.2.7"
   },
   "devDependencies": {
-    "@lessonkit/cli": "^1.5.0",
-    "@lessonkit/lxpack": "^1.5.0",
+    "@lessonkit/cli": "^1.6.0",
+    "@lessonkit/lxpack": "^1.6.0",
     "@testing-library/react": "^16.3.0",
     "@testing-library/dom": "^10.4.1",
     "@types/react": "^19.2.17",