@lessonkit/lxpack 1.5.0 → 1.6.0

package/dist/index.d.cts

@@ -155,6 +155,16 @@ type SpaLessonEntry = {
     path: string;
 };
 declare function resolveSpaLessons(descriptor: LessonkitCourseDescriptor): SpaLessonEntry[];
+/**
+ * Convert a `lessonkit.json` course descriptor to portable interchange JSON for `.lkcourse`.
+ *
+ * @example
+ * ```ts
+ * import { descriptorToInterchange } from "@lessonkit/lxpack";
+ *
+ * const interchange = descriptorToInterchange(manifest.course);
+ * ```
+ */
 declare function descriptorToInterchange(descriptor: LessonkitCourseDescriptor): LessonkitInterchangeV1;
 
 type LxpackInjectedAssessment = {
@@ -199,6 +209,18 @@ type WriteLxpackProjectResult = {
 };
 /**
  * Materialize an LXPack project tree from a LessonKit descriptor (delegates to LXPack 0.6+).
+ *
+ * @example
+ * ```ts
+ * import { writeLxpackProject } from "@lessonkit/lxpack";
+ *
+ * await writeLxpackProject({
+ *   descriptor: courseFromLessonkitJson,
+ *   outDir: ".lxpack/course",
+ *   spaDistDir: "dist",
+ *   projectRoot: process.cwd(),
+ * });
+ * ```
  */
 declare function writeLxpackProject(options: WriteLxpackProjectOptions): Promise<WriteLxpackProjectResult>;
 
@@ -260,6 +282,8 @@ type PackageLessonkitCourseOptions = WriteLxpackProjectOptions & {
     outputBaseDir?: string;
     /** Treat React parity warnings as packaging errors. */
     strictParity?: boolean;
+    /** Treat LXPack build warnings as packaging errors. */
+    strictBuild?: boolean;
 };
 type PackageLessonkitCourseResult = {
     ok: true;
@@ -288,6 +312,21 @@ declare function buildLessonkitProject(options: BuildLessonkitProjectOptions): P
 /**
  * Package a built SPA into SCORM, xAPI, cmi5, or standalone LMS artifacts.
  * Prefer `lessonkit package --target …` in course projects; call directly for custom pipelines.
+ *
+ * @example
+ * ```ts
+ * import { packageLessonkitCourse } from "@lessonkit/lxpack";
+ *
+ * const result = await packageLessonkitCourse({
+ *   descriptor: manifest.course,
+ *   outDir: ".lxpack/course",
+ *   spaDistDir: "dist",
+ *   projectRoot: process.cwd(),
+ *   target: "scorm12",
+ *   strictBuild: true,
+ * });
+ * if (!result.ok) console.error(result.issues);
+ * ```
  */
 declare function packageLessonkitCourse(options: PackageLessonkitCourseOptions): Promise<PackageLessonkitCourseResult>;
 
@@ -311,6 +350,11 @@ declare function validatePackageInputs(options: Pick<PackageLessonkitCourseOptio
 }): ValidatePackageInputsResult;
 declare function remapArtifactPaths(stagingRoot: string, outDir: string, artifactPath: string | undefined): string | undefined;
 
+/**
+ * Reject symlinks and paths escaping dist roots before packaging LMS artifacts.
+ */
+declare function assertSpaDistContentsSafe(spaDirs: Record<string, string>, projectRoot?: string): Promise<void>;
+
 type LessonkitManifestPaths = {
     spaDistDir: string;
     lxpackOutDir: string;
@@ -340,4 +384,121 @@ type ParseManifestResult = {
 declare function parseLessonkitManifest(raw: unknown, label?: string, projectRoot?: string): ParseManifestResult;
 declare function loadLessonkitManifestFromFile(readJson: () => Promise<unknown>, label?: string, projectRoot?: string): Promise<ParseManifestResult>;
 
-export { type AssessmentDescriptor, type BuildLessonkitProjectOptions, type BuildStagingPackageOptions, type BuildStagingPackageResult, type DescriptorValidationIssue, type DescriptorValidationResult, type FillInBlanksAssessmentDescriptor, type LessonDescriptor, type LessonkitCourseDescriptor, type LessonkitExportTarget, type LessonkitManifest, type LessonkitManifestPaths, type LxpackInjectedAssessment, type LxpackRuntimeTheme, type ManifestParseIssue, type MappedLessonkitIds, type McqAssessmentDescriptor, type PackageLessonkitCourseOptions, type PackageLessonkitCourseResult, type PackageValidationIssue, type ParseManifestResult, type ProjectPathsInput, type ReactParityIssue, type SpaLayout, type SpaLessonEntry, type TrueFalseAssessmentDescriptor, type ValidateLessonkitProjectOptions, type ValidatePackageInputsResult, type ValidationIssue, type WriteLxpackProjectOptions, type WriteLxpackProjectResult, assessmentDescriptorToLxpack, buildLessonkitProject, buildStagingPackage, descriptorToInterchange, ensureOutDirParent, escapeShellText, extractAssessments, loadLessonkitManifestFromFile, mapLessonkitIds, packageLessonkitCourse, parseLessonkitManifest, promoteStagingToOutDir, remapArtifactPaths, resolveSafePackageOutputOverride, resolveSpaLessons, themeToLxpackRuntime, validateDescriptor, validateDescriptorForTarget, validateLessonkitProject, validatePackageInputs, validateProjectPaths, validateReactManifestParity, writeLxpackProject };
+type LkcourseEnvelopeV1 = {
+    format: "lkcourse";
+    schemaVersion: 1;
+    lessonkitVersion: string;
+    exportedAt: string;
+    sourceManifest: LessonkitManifest;
+    entries: string[];
+};
+type BlockTreeNodeV1 = {
+    type: string;
+    rawTag?: string;
+    courseId?: string;
+    lessonId?: string;
+    checkId?: string;
+    blockId?: string;
+    nodeId?: string;
+    children?: BlockTreeNodeV1[];
+};
+type BlockTreeV1 = {
+    schemaVersion: 1;
+    sources: string[];
+    blocks: BlockTreeNodeV1[];
+};
+type LkcourseValidationIssue = {
+    path: string;
+    message: string;
+};
+type ExportLkcourseOptions = {
+    projectRoot: string;
+    manifest: LessonkitManifest;
+    outPath?: string;
+    includeBlockTree?: boolean;
+    lessonkitVersion?: string;
+};
+type ExportLkcourseResult = {
+    ok: true;
+    archivePath: string;
+    fileCount: number;
+    includeBlockTree: boolean;
+} | {
+    ok: false;
+    issues: LkcourseValidationIssue[];
+};
+type ValidateLkcourseResult = {
+    ok: true;
+    envelope: LkcourseEnvelopeV1;
+    interchange: LessonkitInterchangeV1;
+} | {
+    ok: false;
+    issues: LkcourseValidationIssue[];
+};
+type ImportLkcourseOptions = {
+    archivePath: string;
+    targetDir: string;
+};
+type ImportLkcourseResult = {
+    ok: true;
+    targetDir: string;
+    manifest: LessonkitManifest;
+    interchange: LessonkitInterchangeV1;
+    fileCount: number;
+} | {
+    ok: false;
+    issues: LkcourseValidationIssue[];
+};
+type ExtractBlockTreeOptions = {
+    projectRoot: string;
+    blockTypes?: string[];
+    appSources?: string[];
+};
+
+type ParseEnvelopeResult = {
+    ok: true;
+    envelope: LkcourseEnvelopeV1;
+} | {
+    ok: false;
+    issues: LkcourseValidationIssue[];
+};
+declare function parseLkcourseEnvelope(raw: unknown, label?: string): ParseEnvelopeResult;
+
+declare function extractBlockTree(options: ExtractBlockTreeOptions): BlockTreeV1;
+
+/**
+ * Build a portable `.lkcourse` zip (manifest envelope + interchange + dist).
+ * Prefer `lessonkit export` in course projects.
+ *
+ * @example
+ * ```ts
+ * import { exportLkcourse } from "@lessonkit/lxpack";
+ *
+ * const result = await exportLkcourse({
+ *   projectRoot: "/path/to/course",
+ *   manifest: parsedLessonkitJson,
+ *   archivePath: "handoff.lkcourse",
+ * });
+ * ```
+ */
+declare function exportLkcourse(options: ExportLkcourseOptions): Promise<ExportLkcourseResult>;
+
+declare function validateLkcourseArchiveEntries(entries: Map<string, Uint8Array>, _archiveLabel: string): ValidateLkcourseResult;
+declare function validateLkcourse(archivePath: string): ValidateLkcourseResult;
+
+/**
+ * Extract a `.lkcourse` archive into a project directory (manifest + dist tree).
+ *
+ * @example
+ * ```ts
+ * import { importLkcourse } from "@lessonkit/lxpack";
+ *
+ * const result = await importLkcourse({
+ *   archivePath: "handoff.lkcourse",
+ *   targetDir: "/path/to/dest",
+ * });
+ * ```
+ */
+declare function importLkcourse(options: ImportLkcourseOptions): Promise<ImportLkcourseResult>;
+
+export { type AssessmentDescriptor, type BlockTreeNodeV1, type BlockTreeV1, type BuildLessonkitProjectOptions, type BuildStagingPackageOptions, type BuildStagingPackageResult, type DescriptorValidationIssue, type DescriptorValidationResult, type ExportLkcourseOptions, type ExportLkcourseResult, type ExtractBlockTreeOptions, type FillInBlanksAssessmentDescriptor, type ImportLkcourseOptions, type ImportLkcourseResult, type LessonDescriptor, type LessonkitCourseDescriptor, type LessonkitExportTarget, type LessonkitManifest, type LessonkitManifestPaths, type LkcourseEnvelopeV1, type LkcourseValidationIssue, type LxpackInjectedAssessment, type LxpackRuntimeTheme, type ManifestParseIssue, type MappedLessonkitIds, type McqAssessmentDescriptor, type PackageLessonkitCourseOptions, type PackageLessonkitCourseResult, type PackageValidationIssue, type ParseManifestResult, type ProjectPathsInput, type ReactParityIssue, type SpaLayout, type SpaLessonEntry, type TrueFalseAssessmentDescriptor, type ValidateLessonkitProjectOptions, type ValidateLkcourseResult, type ValidatePackageInputsResult, type ValidationIssue, type WriteLxpackProjectOptions, type WriteLxpackProjectResult, assertSpaDistContentsSafe, assessmentDescriptorToLxpack, buildLessonkitProject, buildStagingPackage, descriptorToInterchange, ensureOutDirParent, escapeShellText, exportLkcourse, extractAssessments, extractBlockTree, importLkcourse, loadLessonkitManifestFromFile, mapLessonkitIds, packageLessonkitCourse, parseLessonkitManifest, parseLkcourseEnvelope, promoteStagingToOutDir, remapArtifactPaths, resolveSafePackageOutputOverride, resolveSpaLessons, themeToLxpackRuntime, validateDescriptor, validateDescriptorForTarget, validateLessonkitProject, validateLkcourse, validateLkcourseArchiveEntries, validatePackageInputs, validateProjectPaths, validateReactManifestParity, writeLxpackProject };

package/dist/index.d.ts

@@ -155,6 +155,16 @@ type SpaLessonEntry = {
     path: string;
 };
 declare function resolveSpaLessons(descriptor: LessonkitCourseDescriptor): SpaLessonEntry[];
+/**
+ * Convert a `lessonkit.json` course descriptor to portable interchange JSON for `.lkcourse`.
+ *
+ * @example
+ * ```ts
+ * import { descriptorToInterchange } from "@lessonkit/lxpack";
+ *
+ * const interchange = descriptorToInterchange(manifest.course);
+ * ```
+ */
 declare function descriptorToInterchange(descriptor: LessonkitCourseDescriptor): LessonkitInterchangeV1;
 
 type LxpackInjectedAssessment = {
@@ -199,6 +209,18 @@ type WriteLxpackProjectResult = {
 };
 /**
  * Materialize an LXPack project tree from a LessonKit descriptor (delegates to LXPack 0.6+).
+ *
+ * @example
+ * ```ts
+ * import { writeLxpackProject } from "@lessonkit/lxpack";
+ *
+ * await writeLxpackProject({
+ *   descriptor: courseFromLessonkitJson,
+ *   outDir: ".lxpack/course",
+ *   spaDistDir: "dist",
+ *   projectRoot: process.cwd(),
+ * });
+ * ```
  */
 declare function writeLxpackProject(options: WriteLxpackProjectOptions): Promise<WriteLxpackProjectResult>;
 
@@ -260,6 +282,8 @@ type PackageLessonkitCourseOptions = WriteLxpackProjectOptions & {
     outputBaseDir?: string;
     /** Treat React parity warnings as packaging errors. */
     strictParity?: boolean;
+    /** Treat LXPack build warnings as packaging errors. */
+    strictBuild?: boolean;
 };
 type PackageLessonkitCourseResult = {
     ok: true;
@@ -288,6 +312,21 @@ declare function buildLessonkitProject(options: BuildLessonkitProjectOptions): P
 /**
  * Package a built SPA into SCORM, xAPI, cmi5, or standalone LMS artifacts.
  * Prefer `lessonkit package --target …` in course projects; call directly for custom pipelines.
+ *
+ * @example
+ * ```ts
+ * import { packageLessonkitCourse } from "@lessonkit/lxpack";
+ *
+ * const result = await packageLessonkitCourse({
+ *   descriptor: manifest.course,
+ *   outDir: ".lxpack/course",
+ *   spaDistDir: "dist",
+ *   projectRoot: process.cwd(),
+ *   target: "scorm12",
+ *   strictBuild: true,
+ * });
+ * if (!result.ok) console.error(result.issues);
+ * ```
  */
 declare function packageLessonkitCourse(options: PackageLessonkitCourseOptions): Promise<PackageLessonkitCourseResult>;
 
@@ -311,6 +350,11 @@ declare function validatePackageInputs(options: Pick<PackageLessonkitCourseOptio
 }): ValidatePackageInputsResult;
 declare function remapArtifactPaths(stagingRoot: string, outDir: string, artifactPath: string | undefined): string | undefined;
 
+/**
+ * Reject symlinks and paths escaping dist roots before packaging LMS artifacts.
+ */
+declare function assertSpaDistContentsSafe(spaDirs: Record<string, string>, projectRoot?: string): Promise<void>;
+
 type LessonkitManifestPaths = {
     spaDistDir: string;
     lxpackOutDir: string;
@@ -340,4 +384,121 @@ type ParseManifestResult = {
 declare function parseLessonkitManifest(raw: unknown, label?: string, projectRoot?: string): ParseManifestResult;
 declare function loadLessonkitManifestFromFile(readJson: () => Promise<unknown>, label?: string, projectRoot?: string): Promise<ParseManifestResult>;
 
-export { type AssessmentDescriptor, type BuildLessonkitProjectOptions, type BuildStagingPackageOptions, type BuildStagingPackageResult, type DescriptorValidationIssue, type DescriptorValidationResult, type FillInBlanksAssessmentDescriptor, type LessonDescriptor, type LessonkitCourseDescriptor, type LessonkitExportTarget, type LessonkitManifest, type LessonkitManifestPaths, type LxpackInjectedAssessment, type LxpackRuntimeTheme, type ManifestParseIssue, type MappedLessonkitIds, type McqAssessmentDescriptor, type PackageLessonkitCourseOptions, type PackageLessonkitCourseResult, type PackageValidationIssue, type ParseManifestResult, type ProjectPathsInput, type ReactParityIssue, type SpaLayout, type SpaLessonEntry, type TrueFalseAssessmentDescriptor, type ValidateLessonkitProjectOptions, type ValidatePackageInputsResult, type ValidationIssue, type WriteLxpackProjectOptions, type WriteLxpackProjectResult, assessmentDescriptorToLxpack, buildLessonkitProject, buildStagingPackage, descriptorToInterchange, ensureOutDirParent, escapeShellText, extractAssessments, loadLessonkitManifestFromFile, mapLessonkitIds, packageLessonkitCourse, parseLessonkitManifest, promoteStagingToOutDir, remapArtifactPaths, resolveSafePackageOutputOverride, resolveSpaLessons, themeToLxpackRuntime, validateDescriptor, validateDescriptorForTarget, validateLessonkitProject, validatePackageInputs, validateProjectPaths, validateReactManifestParity, writeLxpackProject };
+type LkcourseEnvelopeV1 = {
+    format: "lkcourse";
+    schemaVersion: 1;
+    lessonkitVersion: string;
+    exportedAt: string;
+    sourceManifest: LessonkitManifest;
+    entries: string[];
+};
+type BlockTreeNodeV1 = {
+    type: string;
+    rawTag?: string;
+    courseId?: string;
+    lessonId?: string;
+    checkId?: string;
+    blockId?: string;
+    nodeId?: string;
+    children?: BlockTreeNodeV1[];
+};
+type BlockTreeV1 = {
+    schemaVersion: 1;
+    sources: string[];
+    blocks: BlockTreeNodeV1[];
+};
+type LkcourseValidationIssue = {
+    path: string;
+    message: string;
+};
+type ExportLkcourseOptions = {
+    projectRoot: string;
+    manifest: LessonkitManifest;
+    outPath?: string;
+    includeBlockTree?: boolean;
+    lessonkitVersion?: string;
+};
+type ExportLkcourseResult = {
+    ok: true;
+    archivePath: string;
+    fileCount: number;
+    includeBlockTree: boolean;
+} | {
+    ok: false;
+    issues: LkcourseValidationIssue[];
+};
+type ValidateLkcourseResult = {
+    ok: true;
+    envelope: LkcourseEnvelopeV1;
+    interchange: LessonkitInterchangeV1;
+} | {
+    ok: false;
+    issues: LkcourseValidationIssue[];
+};
+type ImportLkcourseOptions = {
+    archivePath: string;
+    targetDir: string;
+};
+type ImportLkcourseResult = {
+    ok: true;
+    targetDir: string;
+    manifest: LessonkitManifest;
+    interchange: LessonkitInterchangeV1;
+    fileCount: number;
+} | {
+    ok: false;
+    issues: LkcourseValidationIssue[];
+};
+type ExtractBlockTreeOptions = {
+    projectRoot: string;
+    blockTypes?: string[];
+    appSources?: string[];
+};
+
+type ParseEnvelopeResult = {
+    ok: true;
+    envelope: LkcourseEnvelopeV1;
+} | {
+    ok: false;
+    issues: LkcourseValidationIssue[];
+};
+declare function parseLkcourseEnvelope(raw: unknown, label?: string): ParseEnvelopeResult;
+
+declare function extractBlockTree(options: ExtractBlockTreeOptions): BlockTreeV1;
+
+/**
+ * Build a portable `.lkcourse` zip (manifest envelope + interchange + dist).
+ * Prefer `lessonkit export` in course projects.
+ *
+ * @example
+ * ```ts
+ * import { exportLkcourse } from "@lessonkit/lxpack";
+ *
+ * const result = await exportLkcourse({
+ *   projectRoot: "/path/to/course",
+ *   manifest: parsedLessonkitJson,
+ *   archivePath: "handoff.lkcourse",
+ * });
+ * ```
+ */
+declare function exportLkcourse(options: ExportLkcourseOptions): Promise<ExportLkcourseResult>;
+
+declare function validateLkcourseArchiveEntries(entries: Map<string, Uint8Array>, _archiveLabel: string): ValidateLkcourseResult;
+declare function validateLkcourse(archivePath: string): ValidateLkcourseResult;
+
+/**
+ * Extract a `.lkcourse` archive into a project directory (manifest + dist tree).
+ *
+ * @example
+ * ```ts
+ * import { importLkcourse } from "@lessonkit/lxpack";
+ *
+ * const result = await importLkcourse({
+ *   archivePath: "handoff.lkcourse",
+ *   targetDir: "/path/to/dest",
+ * });
+ * ```
+ */
+declare function importLkcourse(options: ImportLkcourseOptions): Promise<ImportLkcourseResult>;
+
+export { type AssessmentDescriptor, type BlockTreeNodeV1, type BlockTreeV1, type BuildLessonkitProjectOptions, type BuildStagingPackageOptions, type BuildStagingPackageResult, type DescriptorValidationIssue, type DescriptorValidationResult, type ExportLkcourseOptions, type ExportLkcourseResult, type ExtractBlockTreeOptions, type FillInBlanksAssessmentDescriptor, type ImportLkcourseOptions, type ImportLkcourseResult, type LessonDescriptor, type LessonkitCourseDescriptor, type LessonkitExportTarget, type LessonkitManifest, type LessonkitManifestPaths, type LkcourseEnvelopeV1, type LkcourseValidationIssue, type LxpackInjectedAssessment, type LxpackRuntimeTheme, type ManifestParseIssue, type MappedLessonkitIds, type McqAssessmentDescriptor, type PackageLessonkitCourseOptions, type PackageLessonkitCourseResult, type PackageValidationIssue, type ParseManifestResult, type ProjectPathsInput, type ReactParityIssue, type SpaLayout, type SpaLessonEntry, type TrueFalseAssessmentDescriptor, type ValidateLessonkitProjectOptions, type ValidateLkcourseResult, type ValidatePackageInputsResult, type ValidationIssue, type WriteLxpackProjectOptions, type WriteLxpackProjectResult, assertSpaDistContentsSafe, assessmentDescriptorToLxpack, buildLessonkitProject, buildStagingPackage, descriptorToInterchange, ensureOutDirParent, escapeShellText, exportLkcourse, extractAssessments, extractBlockTree, importLkcourse, loadLessonkitManifestFromFile, mapLessonkitIds, packageLessonkitCourse, parseLessonkitManifest, parseLkcourseEnvelope, promoteStagingToOutDir, remapArtifactPaths, resolveSafePackageOutputOverride, resolveSpaLessons, themeToLxpackRuntime, validateDescriptor, validateDescriptorForTarget, validateLessonkitProject, validateLkcourse, validateLkcourseArchiveEntries, validatePackageInputs, validateProjectPaths, validateReactManifestParity, writeLxpackProject };