@lessonkit/lxpack 0.9.3 → 1.0.1

package/dist/index.d.cts

@@ -1,9 +1,9 @@
 import { CheckId, CourseId, LessonId } from '@lessonkit/core';
 import { ThemePresetName, LessonkitThemeV1 } from '@lessonkit/themes';
+import { ExportTarget, BuildCourseResult, ValidateCourseResult } from '@lxpack/api';
+export { ExportTarget } from '@lxpack/api';
 import { LessonkitInterchangeV1 } from '@lxpack/validators';
 export { LessonkitInterchangeV1, MaterializeLessonkitOptions, MaterializeLessonkitResult, lessonkitInterchangeSchema, materializeLessonkitProject, parseLessonkitInterchange } from '@lxpack/validators';
-import { ExportTarget, ValidateCourseResult, BuildCourseResult } from '@lxpack/api';
-export { ExportTarget } from '@lxpack/api';
 export { LESSONKIT_TELEMETRY_EVENTS, LessonkitBridgeAction, LessonkitTelemetryEvent, LessonkitTelemetryEventName, TrackingSchemaEvent, mapLessonkitTelemetryToBridgeAction, mapLessonkitTelemetryToLxpack } from '@lxpack/tracking-schema';
 export { t as telemetryEventToLessonkit } from './telemetry-gCxlwc7I.cjs';
 
@@ -53,10 +53,14 @@ type MappedLessonkitIds = {
     checkIds: CheckId[];
 };
 
-type DescriptorValidationIssue = {
+/** Shared validation issue shape across lxpack parsers. */
+type ValidationIssue = {
     path: string;
     message: string;
+    severity?: string;
 };
+
+type DescriptorValidationIssue = ValidationIssue;
 type DescriptorValidationResult = {
     ok: true;
     descriptor: LessonkitCourseDescriptor;
@@ -64,7 +68,8 @@ type DescriptorValidationResult = {
     ok: false;
     issues: DescriptorValidationIssue[];
 };
-declare function validateDescriptor(input: LessonkitCourseDescriptor): DescriptorValidationResult;
+declare function validateDescriptor(input: unknown): DescriptorValidationResult;
+declare function validateDescriptorForTarget(input: unknown, target?: ExportTarget): DescriptorValidationResult;
 
 type ProjectPathsInput = {
     spaDistDir?: string;
@@ -94,7 +99,7 @@ declare function themeToLxpackRuntime(input: {
 }): LxpackRuntimeTheme;
 
 type SpaLessonEntry = {
-    id: string;
+    id: LessonId;
     title: string;
     path: string;
 };
@@ -144,6 +149,40 @@ type WriteLxpackProjectResult = {
  */
 declare function writeLxpackProject(options: WriteLxpackProjectOptions): Promise<WriteLxpackProjectResult>;
 
+/**
+ * Atomically replace `outDir` with the packaged tree at `stagingDir`.
+ * Restores the previous `outDir` when promote fails after a backup rename.
+ */
+declare function promoteStagingToOutDir(stagingDir: string, outDir: string): Promise<void>;
+
+type BuildStagingPackageOptions = WriteLxpackProjectOptions & {
+    descriptor: LessonkitCourseDescriptor;
+    target: ExportTarget;
+    output?: string;
+    dir?: boolean;
+    outputBaseDir?: string;
+};
+type BuildStagingPackageResult = {
+    ok: true;
+    stagingDir: string;
+    build: Extract<BuildCourseResult, {
+        ok: true;
+    }>;
+    outputPath?: string;
+    outputDir?: string;
+} | {
+    ok: false;
+    stagingDir: string;
+    issues: Array<{
+        path?: string;
+        message: string;
+        severity?: string;
+    }>;
+    build?: BuildCourseResult;
+};
+declare function buildStagingPackage(options: BuildStagingPackageOptions): Promise<BuildStagingPackageResult>;
+declare function ensureOutDirParent(outDir: string): Promise<void>;
+
 type ValidateLessonkitProjectOptions = {
     courseDir: string;
     target?: ExportTarget;
@@ -154,7 +193,7 @@ type BuildLessonkitProjectOptions = {
     output?: string;
     dir?: boolean;
     outputBaseDir?: string;
-    assessments?: unknown[];
+    assessments?: LxpackInjectedAssessment[];
 };
 type PackageLessonkitCourseOptions = WriteLxpackProjectOptions & {
     target: ExportTarget;
@@ -186,6 +225,52 @@ type PackageLessonkitCourseResult = {
 };
 declare function validateLessonkitProject(options: ValidateLessonkitProjectOptions): Promise<ValidateCourseResult>;
 declare function buildLessonkitProject(options: BuildLessonkitProjectOptions): Promise<BuildCourseResult>;
+
 declare function packageLessonkitCourse(options: PackageLessonkitCourseOptions): Promise<PackageLessonkitCourseResult>;
 
-export { type AssessmentDescriptor, type BuildLessonkitProjectOptions, type DescriptorValidationIssue, type DescriptorValidationResult, type LessonDescriptor, type LessonkitCourseDescriptor, type LxpackInjectedAssessment, type LxpackRuntimeTheme, type MappedLessonkitIds, type PackageLessonkitCourseOptions, type PackageLessonkitCourseResult, type ProjectPathsInput, type SpaLayout, type SpaLessonEntry, type ValidateLessonkitProjectOptions, type WriteLxpackProjectOptions, type WriteLxpackProjectResult, assessmentDescriptorToLxpack, buildLessonkitProject, descriptorToInterchange, extractAssessments, mapLessonkitIds, packageLessonkitCourse, resolveSafePackageOutputOverride, resolveSpaLessons, themeToLxpackRuntime, validateDescriptor, validateLessonkitProject, validateProjectPaths, writeLxpackProject };
+type PackageValidationIssue = {
+    path?: string;
+    message: string;
+    severity?: string;
+};
+type ValidatePackageInputsResult = {
+    ok: true;
+    outDir: string;
+    projectRoot?: string;
+} | {
+    ok: false;
+    courseDir: string;
+    target: ExportTarget;
+    issues: PackageValidationIssue[];
+};
+declare function validatePackageInputs(options: Pick<PackageLessonkitCourseOptions, "outDir" | "projectRoot" | "outputBaseDir" | "output"> & {
+    target: ExportTarget;
+}): ValidatePackageInputsResult;
+declare function remapArtifactPaths(stagingRoot: string, outDir: string, artifactPath: string | undefined): string | undefined;
+
+type LessonkitManifestPaths = {
+    spaDistDir: string;
+    lxpackOutDir: string;
+    outputBaseDir: string;
+};
+type LessonkitManifest = {
+    schemaVersion: 1;
+    name: string;
+    course: LessonkitCourseDescriptor;
+    paths: LessonkitManifestPaths;
+};
+type ManifestParseIssue = {
+    path: string;
+    message: string;
+};
+type ParseManifestResult = {
+    ok: true;
+    manifest: LessonkitManifest;
+} | {
+    ok: false;
+    issues: ManifestParseIssue[];
+};
+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 LessonDescriptor, type LessonkitCourseDescriptor, type LessonkitManifest, type LessonkitManifestPaths, type LxpackInjectedAssessment, type LxpackRuntimeTheme, type ManifestParseIssue, type MappedLessonkitIds, type PackageLessonkitCourseOptions, type PackageLessonkitCourseResult, type PackageValidationIssue, type ParseManifestResult, type ProjectPathsInput, type SpaLayout, type SpaLessonEntry, type ValidateLessonkitProjectOptions, type ValidatePackageInputsResult, type ValidationIssue, type WriteLxpackProjectOptions, type WriteLxpackProjectResult, assessmentDescriptorToLxpack, buildLessonkitProject, buildStagingPackage, descriptorToInterchange, ensureOutDirParent, extractAssessments, loadLessonkitManifestFromFile, mapLessonkitIds, packageLessonkitCourse, parseLessonkitManifest, promoteStagingToOutDir, remapArtifactPaths, resolveSafePackageOutputOverride, resolveSpaLessons, themeToLxpackRuntime, validateDescriptor, validateDescriptorForTarget, validateLessonkitProject, validatePackageInputs, validateProjectPaths, writeLxpackProject };

package/dist/index.d.ts

@@ -1,9 +1,9 @@
 import { CheckId, CourseId, LessonId } from '@lessonkit/core';
 import { ThemePresetName, LessonkitThemeV1 } from '@lessonkit/themes';
+import { ExportTarget, BuildCourseResult, ValidateCourseResult } from '@lxpack/api';
+export { ExportTarget } from '@lxpack/api';
 import { LessonkitInterchangeV1 } from '@lxpack/validators';
 export { LessonkitInterchangeV1, MaterializeLessonkitOptions, MaterializeLessonkitResult, lessonkitInterchangeSchema, materializeLessonkitProject, parseLessonkitInterchange } from '@lxpack/validators';
-import { ExportTarget, ValidateCourseResult, BuildCourseResult } from '@lxpack/api';
-export { ExportTarget } from '@lxpack/api';
 export { LESSONKIT_TELEMETRY_EVENTS, LessonkitBridgeAction, LessonkitTelemetryEvent, LessonkitTelemetryEventName, TrackingSchemaEvent, mapLessonkitTelemetryToBridgeAction, mapLessonkitTelemetryToLxpack } from '@lxpack/tracking-schema';
 export { t as telemetryEventToLessonkit } from './telemetry-gCxlwc7I.js';
 
@@ -53,10 +53,14 @@ type MappedLessonkitIds = {
     checkIds: CheckId[];
 };
 
-type DescriptorValidationIssue = {
+/** Shared validation issue shape across lxpack parsers. */
+type ValidationIssue = {
     path: string;
     message: string;
+    severity?: string;
 };
+
+type DescriptorValidationIssue = ValidationIssue;
 type DescriptorValidationResult = {
     ok: true;
     descriptor: LessonkitCourseDescriptor;
@@ -64,7 +68,8 @@ type DescriptorValidationResult = {
     ok: false;
     issues: DescriptorValidationIssue[];
 };
-declare function validateDescriptor(input: LessonkitCourseDescriptor): DescriptorValidationResult;
+declare function validateDescriptor(input: unknown): DescriptorValidationResult;
+declare function validateDescriptorForTarget(input: unknown, target?: ExportTarget): DescriptorValidationResult;
 
 type ProjectPathsInput = {
     spaDistDir?: string;
@@ -94,7 +99,7 @@ declare function themeToLxpackRuntime(input: {
 }): LxpackRuntimeTheme;
 
 type SpaLessonEntry = {
-    id: string;
+    id: LessonId;
     title: string;
     path: string;
 };
@@ -144,6 +149,40 @@ type WriteLxpackProjectResult = {
  */
 declare function writeLxpackProject(options: WriteLxpackProjectOptions): Promise<WriteLxpackProjectResult>;
 
+/**
+ * Atomically replace `outDir` with the packaged tree at `stagingDir`.
+ * Restores the previous `outDir` when promote fails after a backup rename.
+ */
+declare function promoteStagingToOutDir(stagingDir: string, outDir: string): Promise<void>;
+
+type BuildStagingPackageOptions = WriteLxpackProjectOptions & {
+    descriptor: LessonkitCourseDescriptor;
+    target: ExportTarget;
+    output?: string;
+    dir?: boolean;
+    outputBaseDir?: string;
+};
+type BuildStagingPackageResult = {
+    ok: true;
+    stagingDir: string;
+    build: Extract<BuildCourseResult, {
+        ok: true;
+    }>;
+    outputPath?: string;
+    outputDir?: string;
+} | {
+    ok: false;
+    stagingDir: string;
+    issues: Array<{
+        path?: string;
+        message: string;
+        severity?: string;
+    }>;
+    build?: BuildCourseResult;
+};
+declare function buildStagingPackage(options: BuildStagingPackageOptions): Promise<BuildStagingPackageResult>;
+declare function ensureOutDirParent(outDir: string): Promise<void>;
+
 type ValidateLessonkitProjectOptions = {
     courseDir: string;
     target?: ExportTarget;
@@ -154,7 +193,7 @@ type BuildLessonkitProjectOptions = {
     output?: string;
     dir?: boolean;
     outputBaseDir?: string;
-    assessments?: unknown[];
+    assessments?: LxpackInjectedAssessment[];
 };
 type PackageLessonkitCourseOptions = WriteLxpackProjectOptions & {
     target: ExportTarget;
@@ -186,6 +225,52 @@ type PackageLessonkitCourseResult = {
 };
 declare function validateLessonkitProject(options: ValidateLessonkitProjectOptions): Promise<ValidateCourseResult>;
 declare function buildLessonkitProject(options: BuildLessonkitProjectOptions): Promise<BuildCourseResult>;
+
 declare function packageLessonkitCourse(options: PackageLessonkitCourseOptions): Promise<PackageLessonkitCourseResult>;
 
-export { type AssessmentDescriptor, type BuildLessonkitProjectOptions, type DescriptorValidationIssue, type DescriptorValidationResult, type LessonDescriptor, type LessonkitCourseDescriptor, type LxpackInjectedAssessment, type LxpackRuntimeTheme, type MappedLessonkitIds, type PackageLessonkitCourseOptions, type PackageLessonkitCourseResult, type ProjectPathsInput, type SpaLayout, type SpaLessonEntry, type ValidateLessonkitProjectOptions, type WriteLxpackProjectOptions, type WriteLxpackProjectResult, assessmentDescriptorToLxpack, buildLessonkitProject, descriptorToInterchange, extractAssessments, mapLessonkitIds, packageLessonkitCourse, resolveSafePackageOutputOverride, resolveSpaLessons, themeToLxpackRuntime, validateDescriptor, validateLessonkitProject, validateProjectPaths, writeLxpackProject };
+type PackageValidationIssue = {
+    path?: string;
+    message: string;
+    severity?: string;
+};
+type ValidatePackageInputsResult = {
+    ok: true;
+    outDir: string;
+    projectRoot?: string;
+} | {
+    ok: false;
+    courseDir: string;
+    target: ExportTarget;
+    issues: PackageValidationIssue[];
+};
+declare function validatePackageInputs(options: Pick<PackageLessonkitCourseOptions, "outDir" | "projectRoot" | "outputBaseDir" | "output"> & {
+    target: ExportTarget;
+}): ValidatePackageInputsResult;
+declare function remapArtifactPaths(stagingRoot: string, outDir: string, artifactPath: string | undefined): string | undefined;
+
+type LessonkitManifestPaths = {
+    spaDistDir: string;
+    lxpackOutDir: string;
+    outputBaseDir: string;
+};
+type LessonkitManifest = {
+    schemaVersion: 1;
+    name: string;
+    course: LessonkitCourseDescriptor;
+    paths: LessonkitManifestPaths;
+};
+type ManifestParseIssue = {
+    path: string;
+    message: string;
+};
+type ParseManifestResult = {
+    ok: true;
+    manifest: LessonkitManifest;
+} | {
+    ok: false;
+    issues: ManifestParseIssue[];
+};
+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 LessonDescriptor, type LessonkitCourseDescriptor, type LessonkitManifest, type LessonkitManifestPaths, type LxpackInjectedAssessment, type LxpackRuntimeTheme, type ManifestParseIssue, type MappedLessonkitIds, type PackageLessonkitCourseOptions, type PackageLessonkitCourseResult, type PackageValidationIssue, type ParseManifestResult, type ProjectPathsInput, type SpaLayout, type SpaLessonEntry, type ValidateLessonkitProjectOptions, type ValidatePackageInputsResult, type ValidationIssue, type WriteLxpackProjectOptions, type WriteLxpackProjectResult, assessmentDescriptorToLxpack, buildLessonkitProject, buildStagingPackage, descriptorToInterchange, ensureOutDirParent, extractAssessments, loadLessonkitManifestFromFile, mapLessonkitIds, packageLessonkitCourse, parseLessonkitManifest, promoteStagingToOutDir, remapArtifactPaths, resolveSafePackageOutputOverride, resolveSpaLessons, themeToLxpackRuntime, validateDescriptor, validateDescriptorForTarget, validateLessonkitProject, validatePackageInputs, validateProjectPaths, writeLxpackProject };