@learnpack/learnpack 5.0.352 → 5.0.354

package/lib/utils/descriptions/s3Storage.js

@@ -0,0 +1,141 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.manifestKey = exports.syllabusKey = void 0;
+exports.fetchExercises = fetchExercises;
+exports.createS3SyllabusSyncStorage = createS3SyllabusSyncStorage;
+exports.createS3DescriptionsStorageFromEnv = createS3DescriptionsStorageFromEnv;
+exports.createS3DescriptionsStorage = createS3DescriptionsStorage;
+const client_s3_1 = require("@aws-sdk/client-s3");
+const client_cloudfront_1 = require("@aws-sdk/client-cloudfront");
+const packageManifest_1 = require("../packageManifest");
+const packageManifestBackfill_1 = require("../s3/packageManifestBackfill");
+const awsCredentials_1 = require("../awsCredentials");
+/**
+ * Published-bucket (S3) adapter for the description flows.
+ *
+ * The published package is the snapshot descriptions are generated from: it is
+ * immutable between publications, unlike the draft in GCS, which keeps moving
+ * while the teacher edits.
+ */
+const syllabusKey = (slug) => `${slug}/.learn/initialSyllabus.json`;
+exports.syllabusKey = syllabusKey;
+const manifestKey = (slug) => `${slug}/${packageManifest_1.PACKAGE_MANIFEST_REL_PATH}`;
+exports.manifestKey = manifestKey;
+const configKeys = (slug) => [
+    `${slug}/.learn/config.json`,
+    `${slug}/config.json`,
+];
+async function fetchExercises(s3, bucket, slug) {
+    for (const key of configKeys(slug)) {
+        // eslint-disable-next-line no-await-in-loop -- the second key is a fallback
+        const config = await (0, packageManifestBackfill_1.fetchJsonObject)(s3, bucket, key);
+        if ((config === null || config === void 0 ? void 0 : config.exercises) && Array.isArray(config.exercises)) {
+            return config.exercises;
+        }
+    }
+    return [];
+}
+function createS3SyllabusSyncStorage(s3, bucket) {
+    return {
+        async listExerciseFolderFileCounts(courseSlug) {
+            const prefix = `${courseSlug}/exercises/`;
+            const keys = await (0, packageManifestBackfill_1.listObjectKeys)(s3, bucket, prefix);
+            const counts = new Map();
+            for (const key of keys) {
+                const segment = key.slice(prefix.length).split("/")[0];
+                if (segment) {
+                    counts.set(segment, (counts.get(segment) || 0) + 1);
+                }
+            }
+            return counts;
+        },
+        async translationLangsBySlug(courseSlug) {
+            const exercises = await fetchExercises(s3, bucket, courseSlug);
+            const map = new Map();
+            for (const exercise of exercises) {
+                const langs = Object.keys(exercise.translations || {})
+                    .map(lang => lang.toLowerCase())
+                    .filter(Boolean);
+                if (langs.length > 0) {
+                    map.set(exercise.slug, [...new Set(langs)]);
+                }
+            }
+            return map;
+        },
+    };
+}
+/**
+ * Storage for the published bucket, wired from the environment. Used by the
+ * post-publish stage and the sweep, which have no CLI flags to read.
+ */
+function createS3DescriptionsStorageFromEnv() {
+    // Validated here so a missing variable fails with its own name, instead of
+    // surfacing minutes later as "Could not load credentials from any providers"
+    // from inside a background job.
+    const credentials = (0, awsCredentials_1.requireAwsCredentials)();
+    const region = (0, awsCredentials_1.awsRegion)();
+    const s3 = new client_s3_1.S3Client({ region, credentials });
+    const distributionId = (process.env.CLOUDFRONT_DISTRIBUTION_ID || "").trim();
+    const cloudFront = distributionId ?
+        {
+            client: new client_cloudfront_1.CloudFrontClient({
+                region,
+                credentials,
+            }),
+            distributionId,
+        } :
+        undefined;
+    if (!cloudFront) {
+        console.warn("[descriptions] CLOUDFRONT_DISTRIBUTION_ID is not set: the manifest will be re-projected but not invalidated");
+    }
+    return createS3DescriptionsStorage(s3, (0, awsCredentials_1.requireS3PackagesBucket)(), {
+        cloudFront,
+    });
+}
+function createS3DescriptionsStorage(s3, bucket, options = {}) {
+    const storage = {
+        async readSyllabus(courseSlug) {
+            return (0, packageManifestBackfill_1.fetchJsonObject)(s3, bucket, (0, exports.syllabusKey)(courseSlug));
+        },
+        async writeSyllabus(courseSlug, syllabus) {
+            await (0, packageManifestBackfill_1.withRetry)(() => s3.send(new client_s3_1.PutObjectCommand({
+                Bucket: bucket,
+                Key: (0, exports.syllabusKey)(courseSlug),
+                Body: JSON.stringify(syllabus, null, 2),
+                ContentType: "application/json",
+            })));
+        },
+        async listExercises(courseSlug) {
+            return fetchExercises(s3, bucket, courseSlug);
+        },
+        async readReadme(courseSlug, exerciseSlug, fileName) {
+            return (0, packageManifestBackfill_1.fetchTextObject)(s3, bucket, `${courseSlug}/exercises/${exerciseSlug}/${fileName}`);
+        },
+        async readManifest(courseSlug) {
+            return (0, packageManifestBackfill_1.fetchJsonObject)(s3, bucket, (0, exports.manifestKey)(courseSlug));
+        },
+        syllabusSyncStorage: createS3SyllabusSyncStorage(s3, bucket),
+    };
+    if (options.reprojectManifest !== false) {
+        storage.reprojectManifest = async (courseSlug) => {
+            var _a;
+            // Preserve the publication timestamp: this is a re-projection of an
+            // already published package, not a new publication.
+            const existing = await (0, packageManifestBackfill_1.fetchJsonObject)(s3, bucket, (0, exports.manifestKey)(courseSlug));
+            const result = await (0, packageManifestBackfill_1.processPackage)(s3, bucket, courseSlug, {
+                dryRun: false,
+                force: false,
+                skipExisting: false,
+                publishedAt: (_a = existing === null || existing === void 0 ? void 0 : existing.publishedAt) !== null && _a !== void 0 ? _a : null,
+            });
+            if (result.status === "failed") {
+                throw new Error(result.error || "manifest projection failed");
+            }
+            if (result.status === "skipped" || !options.cloudFront) {
+                return;
+            }
+            await (0, packageManifestBackfill_1.invalidatePackageManifestPaths)(options.cloudFront.client, options.cloudFront.distributionId, [`/${(0, exports.manifestKey)(courseSlug)}`]);
+        };
+    }
+    return storage;
+}

package/lib/utils/descriptions/workList.d.ts

@@ -0,0 +1,75 @@
+import { Lesson, Syllabus } from "../../models/creator";
+import { ContentFingerprint } from "../descriptionHash";
+/**
+ * Deciding WHAT needs a description, separated from generating it.
+ *
+ * The publish route needs the answer before doing any work (to tell breathecode
+ * whether a second event is coming), and the generation service needs the very
+ * same list right after. Keeping the decision here, pure and content-only,
+ * means both answer identically — the alternative, two implementations of
+ * "is this stale?", is exactly how the backfill and the sweep drifted apart.
+ */
+export type CourseExercise = {
+    slug: string;
+    /** language code -> README file name */
+    translations: Record<string, string>;
+};
+/** README contents by exercise slug and language. */
+export type CourseReadmes = Record<string, Record<string, string>>;
+export type LanguageWork = {
+    lang: string;
+    fingerprint: ContentFingerprint;
+};
+export type StepWork = {
+    exerciseSlug: string;
+    /** Reference into the syllabus; the generation service writes through it. */
+    lesson: Lesson;
+    /** Language the description is written from and translated out of. */
+    baseLanguage: string;
+    baseContent: string;
+    languages: LanguageWork[];
+};
+export type BuildWorkListInput = {
+    syllabus: Syllabus;
+    exercises: CourseExercise[];
+    readmes: CourseReadmes;
+    promptVersion?: number;
+    simhashThreshold?: number;
+    /** Regenerate everything except human-edited descriptions. */
+    force?: boolean;
+};
+export declare function findSyllabusLesson(syllabus: Syllabus, exerciseSlug: string): Lesson | undefined;
+/**
+ * Language a course is actually written in.
+ *
+ * `courseInfo.language` is trusted only when some exercise really has a README
+ * in it; otherwise the language is inferred from the content itself (the most
+ * frequent translation across exercises). Defaulting to "en" when the field is
+ * missing would label Spanish courses as English and generate their
+ * descriptions from a translation instead of the original.
+ */
+export declare function inferCourseBaseLanguage(syllabus: Syllabus, exercises: CourseExercise[]): string | null;
+/**
+ * Whether a (step, language) needs generating. Human-edited descriptions are
+ * never touched; an explicit "not enough content" answer (a stored null with a
+ * fingerprint) is respected until the content itself changes.
+ */
+export declare function needsGeneration(slot: NonNullable<Lesson["translations"]>[string] | undefined, fingerprint: ContentFingerprint, options: {
+    promptVersion: number;
+    simhashThreshold: number;
+    force: boolean;
+}): boolean;
+/** The (step, language) pairs whose description is missing or out of date. */
+export declare function buildDescriptionWorkList(input: BuildWorkListInput): StepWork[];
+/** Total (step, language) pairs in a work list. */
+export declare function countWorkItems(work: StepWork[]): number;
+/**
+ * Cheap "has this course ever been fully processed at this prompt version?"
+ * check, from the syllabus alone.
+ *
+ * Deliberately weaker than the work list: it cannot see content changes because
+ * it never reads a README. That is the point — it lets a batched run skip
+ * finished courses without paying thousands of object reads. Use the work list
+ * whenever correctness matters; use this only as a pre-filter.
+ */
+export declare function isCourseSettled(syllabus: Syllabus, exercises: CourseExercise[], promptVersion?: number): boolean;

package/lib/utils/descriptions/workList.js

@@ -0,0 +1,177 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.findSyllabusLesson = findSyllabusLesson;
+exports.inferCourseBaseLanguage = inferCourseBaseLanguage;
+exports.needsGeneration = needsGeneration;
+exports.buildDescriptionWorkList = buildDescriptionWorkList;
+exports.countWorkItems = countWorkItems;
+exports.isCourseSettled = isCourseSettled;
+const creatorUtilities_1 = require("../creatorUtilities");
+const descriptionHash_1 = require("../descriptionHash");
+const packageManifest_1 = require("../packageManifest");
+function findSyllabusLesson(syllabus, exerciseSlug) {
+    return syllabus.lessons.find(lesson => lesson.uid === exerciseSlug ||
+        (0, creatorUtilities_1.slugify)(lesson.id + "-" + lesson.title) === exerciseSlug);
+}
+/**
+ * Language a course is actually written in.
+ *
+ * `courseInfo.language` is trusted only when some exercise really has a README
+ * in it; otherwise the language is inferred from the content itself (the most
+ * frequent translation across exercises). Defaulting to "en" when the field is
+ * missing would label Spanish courses as English and generate their
+ * descriptions from a translation instead of the original.
+ */
+function inferCourseBaseLanguage(syllabus, exercises) {
+    var _a, _b;
+    const counts = new Map();
+    for (const exercise of exercises) {
+        for (const lang of Object.keys(exercise.translations || {})) {
+            counts.set(lang, (counts.get(lang) || 0) + 1);
+        }
+    }
+    if (counts.size === 0) {
+        return null;
+    }
+    const declared = (_b = (_a = syllabus.courseInfo) === null || _a === void 0 ? void 0 : _a.language) === null || _b === void 0 ? void 0 : _b.toLowerCase();
+    if (declared) {
+        for (const lang of counts.keys()) {
+            if (lang.toLowerCase() === declared) {
+                return lang;
+            }
+        }
+    }
+    let best = null;
+    let bestCount = 0;
+    for (const [lang, count] of counts) {
+        if (count > bestCount) {
+            best = lang;
+            bestCount = count;
+        }
+    }
+    return best;
+}
+/** Language to generate this step from: the course's, when it has it. */
+function resolveStepBaseLanguage(exercise, courseBaseLanguage) {
+    const langs = Object.keys(exercise.translations || {});
+    if (langs.length === 0) {
+        return null;
+    }
+    if (courseBaseLanguage && langs.includes(courseBaseLanguage)) {
+        return courseBaseLanguage;
+    }
+    return langs[0];
+}
+/**
+ * Whether a (step, language) needs generating. Human-edited descriptions are
+ * never touched; an explicit "not enough content" answer (a stored null with a
+ * fingerprint) is respected until the content itself changes.
+ */
+function needsGeneration(slot, fingerprint, options) {
+    var _a;
+    if ((slot === null || slot === void 0 ? void 0 : slot.descriptionSource) === "human") {
+        return false;
+    }
+    if (!slot) {
+        return true;
+    }
+    if (options.force) {
+        return true;
+    }
+    if (slot.descriptionStatus === "error") {
+        return true;
+    }
+    if (((_a = slot.descriptionPromptVersion) !== null && _a !== void 0 ? _a : 0) < options.promptVersion) {
+        return true;
+    }
+    return (0, descriptionHash_1.isDescriptionStale)({ sha256: slot.sourceContentHash, simhash: slot.sourceSimHash }, fingerprint, options.simhashThreshold);
+}
+/** The (step, language) pairs whose description is missing or out of date. */
+function buildDescriptionWorkList(input) {
+    var _a, _b, _c, _d;
+    const promptVersion = (_a = input.promptVersion) !== null && _a !== void 0 ? _a : packageManifest_1.DESCRIPTION_PROMPT_VERSION;
+    const simhashThreshold = (_b = input.simhashThreshold) !== null && _b !== void 0 ? _b : (0, descriptionHash_1.getSimhashThreshold)();
+    const force = (_c = input.force) !== null && _c !== void 0 ? _c : false;
+    const courseBaseLanguage = inferCourseBaseLanguage(input.syllabus, input.exercises);
+    const work = [];
+    for (const exercise of input.exercises) {
+        const lesson = findSyllabusLesson(input.syllabus, exercise.slug);
+        if (!lesson) {
+            continue;
+        }
+        const baseLanguage = resolveStepBaseLanguage(exercise, courseBaseLanguage);
+        if (!baseLanguage) {
+            continue;
+        }
+        const exerciseReadmes = input.readmes[exercise.slug] || {};
+        const baseContent = exerciseReadmes[baseLanguage];
+        if (typeof baseContent !== "string") {
+            continue;
+        }
+        const languages = [];
+        for (const lang of Object.keys(exercise.translations || {})) {
+            const content = exerciseReadmes[lang];
+            if (typeof content !== "string") {
+                continue;
+            }
+            // Each language's staleness is anchored to its OWN content, even though
+            // the description is generated from the base language: that is what makes
+            // "the Spanish README changed" regenerate only Spanish.
+            const fingerprint = (0, descriptionHash_1.fingerprintReadme)(content);
+            if (!needsGeneration((_d = lesson.translations) === null || _d === void 0 ? void 0 : _d[lang], fingerprint, {
+                promptVersion,
+                simhashThreshold,
+                force,
+            })) {
+                continue;
+            }
+            languages.push({ lang, fingerprint });
+        }
+        if (languages.length === 0) {
+            continue;
+        }
+        work.push({
+            exerciseSlug: exercise.slug,
+            lesson,
+            baseLanguage,
+            baseContent,
+            languages,
+        });
+    }
+    return work;
+}
+/** Total (step, language) pairs in a work list. */
+function countWorkItems(work) {
+    return work.reduce((total, step) => total + step.languages.length, 0);
+}
+/**
+ * Cheap "has this course ever been fully processed at this prompt version?"
+ * check, from the syllabus alone.
+ *
+ * Deliberately weaker than the work list: it cannot see content changes because
+ * it never reads a README. That is the point — it lets a batched run skip
+ * finished courses without paying thousands of object reads. Use the work list
+ * whenever correctness matters; use this only as a pre-filter.
+ */
+function isCourseSettled(syllabus, exercises, promptVersion = packageManifest_1.DESCRIPTION_PROMPT_VERSION) {
+    var _a, _b;
+    for (const exercise of exercises) {
+        const lesson = findSyllabusLesson(syllabus, exercise.slug);
+        if (!lesson) {
+            return false;
+        }
+        for (const lang of Object.keys(exercise.translations || {})) {
+            const slot = (_a = lesson.translations) === null || _a === void 0 ? void 0 : _a[lang];
+            if ((slot === null || slot === void 0 ? void 0 : slot.descriptionSource) === "human") {
+                continue;
+            }
+            if (!slot ||
+                slot.descriptionStatus === "error" ||
+                !slot.sourceContentHash ||
+                ((_b = slot.descriptionPromptVersion) !== null && _b !== void 0 ? _b : 0) < promptVersion) {
+                return false;
+            }
+        }
+    }
+    return true;
+}

package/lib/utils/gcsBucketName.d.ts

@@ -0,0 +1,10 @@
+/**
+ * The draft bucket name, required rather than defaulted.
+ *
+ * The code used to fall back to "learnpack-packages", a name the service
+ * account cannot reach: with the variable missing, the process would start
+ * cleanly and then fail with a 403 on every single object operation. Failing at
+ * boot with the reason turns a puzzling runtime outage into an obvious
+ * misconfiguration.
+ */
+export declare function requireGcsBucketName(): string;

package/lib/utils/gcsBucketName.js

@@ -0,0 +1,19 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.requireGcsBucketName = requireGcsBucketName;
+/**
+ * The draft bucket name, required rather than defaulted.
+ *
+ * The code used to fall back to "learnpack-packages", a name the service
+ * account cannot reach: with the variable missing, the process would start
+ * cleanly and then fail with a 403 on every single object operation. Failing at
+ * boot with the reason turns a puzzling runtime outage into an obvious
+ * misconfiguration.
+ */
+function requireGcsBucketName() {
+    const name = (process.env.GCP_BUCKET_NAME || "").trim();
+    if (!name) {
+        throw new Error("GCP_BUCKET_NAME (env) is required: it names the bucket holding course drafts");
+    }
+    return name;
+}

package/lib/utils/packageManifest.d.ts

@@ -4,6 +4,8 @@ import { Exercise } from "./configBuilder";
 export declare const PACKAGE_MANIFEST_FILENAME = "package-manifest.json";
 export declare const PACKAGE_MANIFEST_REL_PATH = ".learn/package-manifest.json";
 export declare const SCHEMA_VERSION = 1;
+export declare const DESCRIPTION_PROMPT_VERSION = 1;
+export declare const DESCRIPTION_TARGET_WORD_COUNT = 25;
 export type LessonType = "READ" | "CODE" | "QUIZ";
 export type PackageManifestLesson = {
     id: string;
@@ -46,12 +48,32 @@ export type PackageManifestBuildInput = {
 };
 export declare function packageManifestGcsPath(courseSlug: string): string;
 export declare function resolvePreviewUrl(slug: string, preview?: string): string;
+/**
+ * Lesson id when no syllabus entry matches: the numeric prefix of the folder.
+ *
+ * Exported because `legacyPackageRepair` has to synthesize syllabus ids with
+ * exactly this rule — a repaired package whose ids differed from the ones its
+ * manifest already carries would look like a content change to every consumer.
+ */
+export declare function deriveLessonId(exerciseSlug: string): string;
 export declare function extractReadmeH1(body: string): string | null;
 export declare function normalizeReadmeTitle(raw: string): string | null;
 export declare function buildPackageManifestFromSources(input: PackageManifestBuildInput): PackageManifest;
 export declare function parseReadmeContent(content: string): ReadmeFrontmatter;
 export declare function comparePackageManifests(existing: PackageManifest | null, next: PackageManifest): "created" | "updated" | "skipped";
 export declare function serializePackageManifest(manifest: PackageManifest): string;
+/** The manifest as it travels inside a publication event. */
+export type PackageManifestEventView = Omit<PackageManifest, "generatedAt">;
+/**
+ * Project a manifest into the shape sent to breathecode.
+ *
+ * Today this is nearly the identity — only `generatedAt`, an internal detail of
+ * the projection, is dropped. It exists as an explicit pick so that fields
+ * added to the manifest later (hashes, generation flags) do not silently become
+ * part of an external contract: joining the event payload has to be a decision
+ * visible in a diff.
+ */
+export declare function serializePackageManifestForEvent(manifest: PackageManifest): PackageManifestEventView;
 export declare function generateAndPersistPackageManifest(bucket: Bucket, courseSlug: string, options: {
     publishedAt: string | null;
     localDir?: string;

package/lib/utils/packageManifest.js

@@ -1,14 +1,16 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.SCHEMA_VERSION = exports.PACKAGE_MANIFEST_REL_PATH = exports.PACKAGE_MANIFEST_FILENAME = void 0;
+exports.DESCRIPTION_TARGET_WORD_COUNT = exports.DESCRIPTION_PROMPT_VERSION = exports.SCHEMA_VERSION = exports.PACKAGE_MANIFEST_REL_PATH = exports.PACKAGE_MANIFEST_FILENAME = void 0;
 exports.packageManifestGcsPath = packageManifestGcsPath;
 exports.resolvePreviewUrl = resolvePreviewUrl;
+exports.deriveLessonId = deriveLessonId;
 exports.extractReadmeH1 = extractReadmeH1;
 exports.normalizeReadmeTitle = normalizeReadmeTitle;
 exports.buildPackageManifestFromSources = buildPackageManifestFromSources;
 exports.parseReadmeContent = parseReadmeContent;
 exports.comparePackageManifests = comparePackageManifests;
 exports.serializePackageManifest = serializePackageManifest;
+exports.serializePackageManifestForEvent = serializePackageManifestForEvent;
 exports.generateAndPersistPackageManifest = generateAndPersistPackageManifest;
 const tslib_1 = require("tslib");
 const fs = require("fs");
@@ -22,6 +24,13 @@ const frontMatter = require("front-matter");
 exports.PACKAGE_MANIFEST_FILENAME = "package-manifest.json";
 exports.PACKAGE_MANIFEST_REL_PATH = ".learn/package-manifest.json";
 exports.SCHEMA_VERSION = 1;
+// Version of the Rigobot prompt/model used to generate step descriptions. It
+// travels inside the completion inputs, so bumping it both busts Rigobot's
+// cache and marks every description stored at a lower version for regeneration.
+// Keep in sync with the prompt body provisioned in Rigobot.
+exports.DESCRIPTION_PROMPT_VERSION = 1;
+// Target length, in words, of a generated step description.
+exports.DESCRIPTION_TARGET_WORD_COUNT = 25;
 const VALID_LESSON_TYPES = new Set(["READ", "CODE", "QUIZ"]);
 function packageManifestGcsPath(courseSlug) {
     return `courses/${courseSlug}/${exports.PACKAGE_MANIFEST_REL_PATH}`;
@@ -41,6 +50,13 @@ function findSyllabusLesson(exerciseSlug, lessons) {
         return candidates.includes(exerciseSlug);
     });
 }
+/**
+ * Lesson id when no syllabus entry matches: the numeric prefix of the folder.
+ *
+ * Exported because `legacyPackageRepair` has to synthesize syllabus ids with
+ * exactly this rule — a repaired package whose ids differed from the ones its
+ * manifest already carries would look like a content change to every consumer.
+ */
 function deriveLessonId(exerciseSlug) {
     const match = exerciseSlug.match(/^(\d+(?:\.\d+)?)/);
     return match ? match[1] : exerciseSlug;
@@ -94,11 +110,16 @@ function resolveLessonTitle(exercise, sidebar, syllabusLesson, courseLang, readm
     }
     return titles;
 }
-function resolveLessonDescriptions(exercise) {
+function resolveLessonDescriptions(exercise, syllabusLesson) {
+    var _a, _b, _c;
     const description = {};
+    // Descriptions are a projection: the source of truth lives in the syllabus
+    // lesson (translations[lang].description), populated by the sweep/backfill.
+    // When absent we emit null (the frontend hides the area) rather than a
+    // low-quality placeholder.
     for (const lang of Object.keys(exercise.translations)) {
-        // TODO: add description content
-        description[lang] = null;
+        description[lang] =
+            (_c = (_b = (_a = syllabusLesson === null || syllabusLesson === void 0 ? void 0 : syllabusLesson.translations) === null || _a === void 0 ? void 0 : _a[lang]) === null || _b === void 0 ? void 0 : _b.description) !== null && _c !== void 0 ? _c : null;
     }
     return description;
 }
@@ -134,7 +155,7 @@ function buildPackageManifestFromSources(input) {
             position: exercise.position,
             type,
             title: resolveLessonTitle(exercise, sidebar, syllabusLesson, courseLang, (_b = readmeFrontmatters[exercise.slug]) !== null && _b !== void 0 ? _b : {}),
-            description: resolveLessonDescriptions(exercise),
+            description: resolveLessonDescriptions(exercise, syllabusLesson),
             video: resolveLessonVideos(exercise, readmeFrontmatters),
         };
     });
@@ -184,6 +205,37 @@ function comparePackageManifests(existing, next) {
 function serializePackageManifest(manifest) {
     return JSON.stringify(manifest, null, 2);
 }
+/**
+ * Project a manifest into the shape sent to breathecode.
+ *
+ * Today this is nearly the identity — only `generatedAt`, an internal detail of
+ * the projection, is dropped. It exists as an explicit pick so that fields
+ * added to the manifest later (hashes, generation flags) do not silently become
+ * part of an external contract: joining the event payload has to be a decision
+ * visible in a diff.
+ */
+function serializePackageManifestForEvent(manifest) {
+    return {
+        schemaVersion: manifest.schemaVersion,
+        publishedAt: manifest.publishedAt,
+        slug: manifest.slug,
+        title: manifest.title,
+        description: manifest.description,
+        preview: manifest.preview,
+        technologies: manifest.technologies,
+        difficulty: manifest.difficulty,
+        duration: manifest.duration,
+        lessons: manifest.lessons.map(lesson => ({
+            id: lesson.id,
+            slug: lesson.slug,
+            position: lesson.position,
+            type: lesson.type,
+            title: lesson.title,
+            description: lesson.description,
+            video: lesson.video,
+        })),
+    };
+}
 async function readReadmeFrontmatter(bucket, exerciseSlug, lang, readmePath) {
     try {
         const [buf] = await bucket.file(readmePath).download();

package/lib/utils/publishEvents.d.ts

@@ -0,0 +1,66 @@
+import { PackageManifest, PackageManifestEventView } from "./packageManifest";
+/**
+ * Publication events sent to breathecode.
+ *
+ * They are emitted from here, and not from Rigobot, because learnpack-cli is
+ * the only party that witnesses the facts: Rigobot's part ends when the zip is
+ * deployed, before the breathecode asset sync, and it never sees the end of the
+ * asynchronous description stage.
+ *
+ * Transport is the existing telemetry endpoint. The discriminator is a
+ * top-level `event` key, which is what breathecode's webhook log already looks
+ * for; a body without it keeps being processed as plain telemetry.
+ *
+ * `package_slug` and `package_id` are duplicated at the top level on purpose:
+ * `LearnPack.add_webhook_to_log` fills the indexed columns from there, so
+ * without them the events would land as rows nobody can filter in the webhook
+ * viewer.
+ */
+export declare const PACKAGE_PUBLISHED_EVENT = "package_published";
+export declare const PACKAGE_MANIFEST_UPDATED_EVENT = "package_manifest_updated";
+/** Whether a second event is coming for this publication. */
+export type DescriptionsOutcome = "queued" | "up_to_date";
+export type PublishEventEnvelope = {
+    event: string;
+    package_slug: string;
+    package_id?: number;
+    payload: Record<string, unknown>;
+};
+export type PackagePublishedPayload = {
+    publish_id: string;
+    package: Record<string, unknown> | null;
+    manifest: PackageManifestEventView | null;
+    descriptions: DescriptionsOutcome;
+};
+export type PackageManifestUpdatedPayload = {
+    publish_id: string;
+    status: "success" | "failed";
+    package: Record<string, unknown> | null;
+    manifest: PackageManifestEventView | null;
+    stats?: {
+        generated: number;
+        failed: number;
+        missing: number;
+    };
+};
+export type PublishEventContext = {
+    publishId: string;
+    courseSlug: string;
+    /** `GET /v1/learnpack/package/{slug}/` from Rigobot. */
+    packageInfo: Record<string, unknown> | null;
+    manifest: PackageManifest | null;
+};
+export declare function buildPackagePublishedEvent(context: PublishEventContext, descriptions: DescriptionsOutcome): PublishEventEnvelope;
+export declare function buildPackageManifestUpdatedEvent(context: PublishEventContext, status: "success" | "failed", stats?: PackageManifestUpdatedPayload["stats"]): PublishEventEnvelope;
+/**
+ * Fire and forget: a publication must never fail because breathecode is down,
+ * so every error is swallowed and logged. Returns whether it was delivered, for
+ * the journal, not for control flow.
+ */
+export declare function sendPublishEvent(envelope: PublishEventEnvelope, breathecodeToken: string, timeoutMs?: number): Promise<boolean>;
+/**
+ * Package information for the event payload, straight from Rigobot's own
+ * serializer so the shape stays owned by the system that owns the model.
+ * Returns null on failure: an event with less context still beats no event.
+ */
+export declare function fetchPackageInfo(courseSlug: string, rigobotToken: string): Promise<Record<string, unknown> | null>;