@learnpack/learnpack 5.0.352 → 5.0.354

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

@@ -0,0 +1,49 @@
+import { Syllabus } from "../../models/creator";
+import { CourseDescriptionsStorage } from "./generateCourseDescriptions";
+import { CourseExercise, CourseReadmes } from "./workList";
+/**
+ * Copy descriptions from the published syllabus back into the draft one.
+ *
+ * Descriptions are generated against the published package because it is an
+ * immutable snapshot. The draft in GCS, meanwhile, keeps moving: between the
+ * publication and the moment the descriptions land, steps may have been added,
+ * removed, renamed, reordered or edited.
+ *
+ * The guard against that drift is the content hash, not a timestamp or a
+ * position: a description is copied only when the draft README hashes to the
+ * very content the description was generated from. Anything that moved simply
+ * misses and waits for the next publication — a stale description is never
+ * written onto content it does not describe.
+ *
+ * Without this mirror the draft would never hold a description, and every
+ * publication would regenerate the whole course from scratch: the freshness
+ * check reads the fingerprints stored in the syllabus that travels inside the
+ * zip.
+ */
+export type MirrorResult = {
+    /** (step, language) pairs copied into the draft. */
+    copied: number;
+    /** Pairs with no reusable description: content moved on, or none published. */
+    missed: number;
+    /** Pairs the draft already had up to date. */
+    fresh: number;
+};
+export type MirrorOptions = {
+    promptVersion?: number;
+    dryRun?: boolean;
+    concurrency?: number;
+};
+/**
+ * Pure core: writes into `targetSyllabus` in place. Callers own the I/O, which
+ * keeps the drift rules testable without a bucket.
+ */
+export declare function mirrorDescriptionsIntoSyllabus(input: {
+    sourceSyllabus: Syllabus | null;
+    targetSyllabus: Syllabus;
+    exercises: CourseExercise[];
+    /** READMEs of the TARGET (draft), which is what must match the hash. */
+    readmes: CourseReadmes;
+    promptVersion?: number;
+}): MirrorResult;
+/** Read the draft, mirror into it, and save it when something changed. */
+export declare function mirrorDescriptionsToDraft(storage: CourseDescriptionsStorage, courseSlug: string, sourceSyllabus: Syllabus | null, options?: MirrorOptions): Promise<MirrorResult>;

package/lib/utils/descriptions/mirrorDescriptions.js

@@ -0,0 +1,109 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.mirrorDescriptionsIntoSyllabus = mirrorDescriptionsIntoSyllabus;
+exports.mirrorDescriptionsToDraft = mirrorDescriptionsToDraft;
+const descriptionHash_1 = require("../descriptionHash");
+const packageManifest_1 = require("../packageManifest");
+const generateCourseDescriptions_1 = require("./generateCourseDescriptions");
+const workList_1 = require("./workList");
+function emptyMirrorResult() {
+    return { copied: 0, missed: 0, fresh: 0 };
+}
+/**
+ * Pure core: writes into `targetSyllabus` in place. Callers own the I/O, which
+ * keeps the drift rules testable without a bucket.
+ */
+function mirrorDescriptionsIntoSyllabus(input) {
+    var _a, _b, _c, _d, _e, _f, _g;
+    const result = emptyMirrorResult();
+    if (!input.sourceSyllabus) {
+        return result;
+    }
+    const promptVersion = (_a = input.promptVersion) !== null && _a !== void 0 ? _a : packageManifest_1.DESCRIPTION_PROMPT_VERSION;
+    for (const exercise of input.exercises) {
+        const targetLesson = (0, workList_1.findSyllabusLesson)(input.targetSyllabus, exercise.slug);
+        if (!targetLesson) {
+            // The step is not in the draft (removed, or renamed after publishing).
+            continue;
+        }
+        const sourceLesson = (0, workList_1.findSyllabusLesson)(input.sourceSyllabus, exercise.slug);
+        const exerciseReadmes = input.readmes[exercise.slug] || {};
+        for (const lang of Object.keys(exercise.translations || {})) {
+            const content = exerciseReadmes[lang];
+            if (typeof content !== "string") {
+                continue;
+            }
+            const fingerprint = (0, descriptionHash_1.fingerprintReadme)(content);
+            const targetSlot = (_b = targetLesson.translations) === null || _b === void 0 ? void 0 : _b[lang];
+            if ((targetSlot === null || targetSlot === void 0 ? void 0 : targetSlot.descriptionSource) === "human") {
+                result.fresh += 1;
+                continue;
+            }
+            if ((targetSlot === null || targetSlot === void 0 ? void 0 : targetSlot.sourceContentHash) === fingerprint.sha256 &&
+                ((_c = targetSlot === null || targetSlot === void 0 ? void 0 : targetSlot.descriptionPromptVersion) !== null && _c !== void 0 ? _c : 0) >= promptVersion) {
+                result.fresh += 1;
+                continue;
+            }
+            const sourceSlot = (_d = sourceLesson === null || sourceLesson === void 0 ? void 0 : sourceLesson.translations) === null || _d === void 0 ? void 0 : _d[lang];
+            // The hash guard: only reuse a description generated from exactly this
+            // content. Note a published `description: null` is reusable too — it is a
+            // real answer ("not enough content to describe"), not a missing one.
+            const reusable = sourceSlot !== undefined &&
+                sourceSlot.sourceContentHash === fingerprint.sha256 &&
+                ((_e = sourceSlot.descriptionPromptVersion) !== null && _e !== void 0 ? _e : 0) >= promptVersion &&
+                sourceSlot.descriptionStatus !== "error";
+            if (!reusable) {
+                result.missed += 1;
+                continue;
+            }
+            if (!targetLesson.translations) {
+                targetLesson.translations = {};
+            }
+            if (!targetLesson.translations[lang]) {
+                targetLesson.translations[lang] = {
+                    completionId: 0,
+                    startedAt: Date.now(),
+                };
+            }
+            const destination = targetLesson.translations[lang];
+            destination.description = (_f = sourceSlot.description) !== null && _f !== void 0 ? _f : null;
+            destination.descriptionStatus = sourceSlot.description ?
+                "generated" :
+                "none";
+            destination.descriptionSource = "auto";
+            destination.descriptionPromptVersion =
+                (_g = sourceSlot.descriptionPromptVersion) !== null && _g !== void 0 ? _g : promptVersion;
+            destination.sourceContentHash = fingerprint.sha256;
+            destination.sourceSimHash = fingerprint.simhash;
+            result.copied += 1;
+        }
+    }
+    return result;
+}
+/** Read the draft, mirror into it, and save it when something changed. */
+async function mirrorDescriptionsToDraft(storage, courseSlug, sourceSyllabus, options = {}) {
+    var _a;
+    if (!sourceSyllabus) {
+        return emptyMirrorResult();
+    }
+    const targetSyllabus = await storage.readSyllabus(courseSlug);
+    if (!targetSyllabus) {
+        return emptyMirrorResult();
+    }
+    const exercises = await storage.listExercises(courseSlug);
+    if (exercises.length === 0) {
+        return emptyMirrorResult();
+    }
+    const readmes = await (0, generateCourseDescriptions_1.readCourseReadmes)(storage, courseSlug, exercises, (_a = options.concurrency) !== null && _a !== void 0 ? _a : generateCourseDescriptions_1.DEFAULT_DESCRIPTIONS_CONCURRENCY);
+    const result = mirrorDescriptionsIntoSyllabus({
+        sourceSyllabus,
+        targetSyllabus,
+        exercises,
+        readmes,
+        promptVersion: options.promptVersion,
+    });
+    if (result.copied > 0 && !options.dryRun) {
+        await storage.writeSyllabus(courseSlug, targetSyllabus);
+    }
+    return result;
+}

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

@@ -0,0 +1,69 @@
+import { Bucket } from "@google-cloud/storage";
+import { JournalStorage, PublishJournal } from "../publishJournal";
+import { CourseDescriptionsStorage, GenerateCourseDescriptionsOptions, GenerateCourseDescriptionsResult } from "./generateCourseDescriptions";
+import { MirrorResult } from "./mirrorDescriptions";
+import { PublishEventContext, sendPublishEvent } from "../publishEvents";
+import { CourseExercise } from "./workList";
+/**
+ * Stage B of a publication: generate the descriptions the new content needs.
+ *
+ * It runs in the background, after the HTTP response, because a single
+ * completion takes ~15s and a course may need several — far past any request
+ * limit. The publication itself is already finished and durable by then; this
+ * stage only enriches the published package.
+ */
+/**
+ * Whether the freshly built package needs any description, decided from the
+ * build directory that is still on disk after zipping.
+ *
+ * Reading from disk (instead of re-reading GCS or S3) is free and, at this
+ * exact moment, all three hold the same content: the answer is what the publish
+ * response promises to breathecode, so it must be cheap enough to compute
+ * before responding.
+ */
+/** Reads a path relative to the build root; null when it does not exist. */
+export type BuildFileReader = (relativePath: string) => string | null;
+export declare function createBuildFileReader(buildRoot: string): BuildFileReader;
+export declare function countPendingDescriptions(buildRoot: string, exercises: CourseExercise[], readFile?: BuildFileReader): number;
+export type PublishDescriptionsStageResult = {
+    generation: GenerateCourseDescriptionsResult | null;
+    mirror: MirrorResult | null;
+    /** False when generation failed outright; drives the event status. */
+    succeeded: boolean;
+};
+/**
+ * Generate against the published package, then mirror what still matches back
+ * into the draft. Stages are recorded as they go so an interrupted run can be
+ * resumed by the sweep.
+ */
+export declare function runPublishDescriptionsStage(params: {
+    courseSlug: string;
+    rigobotToken: string;
+    gcsBucket?: Bucket;
+    journal: PublishJournal;
+    journalStorage: JournalStorage;
+    /** Injection points for tests; production resolves them from env/bucket. */
+    publishedStorage?: CourseDescriptionsStorage;
+    draftStorage?: CourseDescriptionsStorage;
+    generate?: GenerateCourseDescriptionsOptions["generate"];
+}): Promise<PublishDescriptionsStageResult>;
+/**
+ * Entry point for the detached run after publishing. Never throws: it is not
+ * awaited by anyone, so an escaping rejection would only surface as an
+ * unhandled promise.
+ */
+export declare function runDescriptionsStageAfterPublish(params: {
+    courseSlug: string;
+    gcsBucket?: Bucket;
+    journal: PublishJournal;
+    journalStorage: JournalStorage;
+    hasWork: boolean;
+    /** Present when the caller announced `descriptions: "queued"`. */
+    eventContext?: PublishEventContext;
+    breathecodeToken?: string;
+    publishedStorage?: CourseDescriptionsStorage;
+    draftStorage?: CourseDescriptionsStorage;
+    generate?: GenerateCourseDescriptionsOptions["generate"];
+    /** Injection point for tests. */
+    emit?: typeof sendPublishEvent;
+}): Promise<PublishDescriptionsStageResult>;

package/lib/utils/descriptions/publishStage.js

@@ -0,0 +1,245 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createBuildFileReader = createBuildFileReader;
+exports.countPendingDescriptions = countPendingDescriptions;
+exports.runPublishDescriptionsStage = runPublishDescriptionsStage;
+exports.runDescriptionsStageAfterPublish = runDescriptionsStageAfterPublish;
+const fs = require("fs");
+const path = require("path");
+const publishJournal_1 = require("../publishJournal");
+const generateCourseDescriptions_1 = require("./generateCourseDescriptions");
+const gcsStorage_1 = require("./gcsStorage");
+const mirrorDescriptions_1 = require("./mirrorDescriptions");
+const s3Storage_1 = require("./s3Storage");
+const publishEvents_1 = require("../publishEvents");
+const workList_1 = require("./workList");
+function createBuildFileReader(buildRoot) {
+    return relativePath => {
+        try {
+            return fs.readFileSync(path.join(buildRoot, ...relativePath.split("/")), "utf8");
+        }
+        catch (_a) {
+            return null;
+        }
+    };
+}
+function countPendingDescriptions(buildRoot, exercises, readFile = createBuildFileReader(buildRoot)) {
+    const rawSyllabus = readFile(".learn/initialSyllabus.json");
+    if (!rawSyllabus) {
+        return 0;
+    }
+    let syllabus;
+    try {
+        syllabus = JSON.parse(rawSyllabus);
+    }
+    catch (_a) {
+        return 0;
+    }
+    const readmes = {};
+    for (const exercise of exercises) {
+        for (const [lang, fileName] of Object.entries(exercise.translations || {})) {
+            const content = readFile(`exercises/${exercise.slug}/${fileName}`);
+            if (content === null) {
+                // Missing translation file: nothing to fingerprint, nothing to ask for.
+                continue;
+            }
+            if (!readmes[exercise.slug]) {
+                readmes[exercise.slug] = {};
+            }
+            readmes[exercise.slug][lang] = content;
+        }
+    }
+    return (0, workList_1.countWorkItems)((0, workList_1.buildDescriptionWorkList)({ syllabus, exercises, readmes }));
+}
+/**
+ * Generate against the published package, then mirror what still matches back
+ * into the draft. Stages are recorded as they go so an interrupted run can be
+ * resumed by the sweep.
+ */
+async function runPublishDescriptionsStage(params) {
+    var _a, _b;
+    const { courseSlug, journal, journalStorage } = params;
+    const publishedStorage = (_a = params.publishedStorage) !== null && _a !== void 0 ? _a : (0, s3Storage_1.createS3DescriptionsStorageFromEnv)();
+    await (0, publishJournal_1.markStage)(journalStorage, journal, "descriptions", "running");
+    let generation = null;
+    try {
+        generation = await (0, generateCourseDescriptions_1.generateCourseDescriptions)(publishedStorage, courseSlug, {
+            token: params.rigobotToken,
+            reconcile: true,
+            generate: params.generate,
+        });
+    }
+    catch (error) {
+        await (0, publishJournal_1.markStage)(journalStorage, journal, "descriptions", "failed", {
+            error: error.message,
+        });
+        return { generation: null, mirror: null, succeeded: false };
+    }
+    const succeeded = generation.status !== "failed";
+    await (0, publishJournal_1.markStage)(journalStorage, journal, "descriptions", succeeded ? "done" : "failed", {
+        error: succeeded ? undefined : generation.errors.join("; "),
+        meta: {
+            steps: generation.steps,
+            generated: generation.generated,
+            failed: generation.failed,
+            missing: generation.missing,
+            durationsSeconds: generation.durationsSeconds,
+        },
+    });
+    if (!succeeded) {
+        return { generation, mirror: null, succeeded: false };
+    }
+    // Mirror back so the draft keeps the fingerprints: without it the next
+    // publication would regenerate the whole course.
+    await (0, publishJournal_1.markStage)(journalStorage, journal, "gcsMirror", "running");
+    try {
+        const draftStorage = (_b = params.draftStorage) !== null && _b !== void 0 ? _b : (0, gcsStorage_1.createGcsDescriptionsStorage)(params.gcsBucket);
+        const publishedSyllabus = await publishedStorage.readSyllabus(courseSlug);
+        const mirror = await (0, mirrorDescriptions_1.mirrorDescriptionsToDraft)(draftStorage, courseSlug, publishedSyllabus);
+        await (0, publishJournal_1.markStage)(journalStorage, journal, "gcsMirror", "done", {
+            meta: mirror,
+        });
+        return { generation, mirror, succeeded: true };
+    }
+    catch (error) {
+        // The published package is already correct; only the draft lags behind.
+        await (0, publishJournal_1.markStage)(journalStorage, journal, "gcsMirror", "failed", {
+            error: error.message,
+        });
+        return { generation, mirror: null, succeeded: true };
+    }
+}
+/**
+ * Entry point for the detached run after publishing. Never throws: it is not
+ * awaited by anyone, so an escaping rejection would only surface as an
+ * unhandled promise.
+ */
+async function runDescriptionsStageAfterPublish(params) {
+    var _a, _b, _c, _d, _e, _f;
+    const { courseSlug, journal, journalStorage } = params;
+    let outcome = {
+        generation: null,
+        mirror: null,
+        succeeded: true,
+    };
+    // Resolved on demand: the common "nothing to describe" path must not build
+    // AWS clients it will never use.
+    let resolved = params.publishedStorage;
+    const publishedStorage = () => {
+        if (!resolved) {
+            resolved = (0, s3Storage_1.createS3DescriptionsStorageFromEnv)();
+        }
+        return resolved;
+    };
+    try {
+        if (!params.hasWork) {
+            // Nothing changed enough to describe; both stages are settled, and no
+            // second event was promised, so none is sent.
+            await (0, publishJournal_1.markStage)(journalStorage, journal, "descriptions", "done", {
+                meta: { reason: "up_to_date" },
+            });
+            await (0, publishJournal_1.markStage)(journalStorage, journal, "gcsMirror", "done", {
+                meta: { reason: "up_to_date" },
+            });
+            await (0, publishJournal_1.markStage)(journalStorage, journal, "manifestEvent", "done", {
+                meta: { reason: "not_promised" },
+            });
+            return outcome;
+        }
+        // Descriptions are platform enrichment, not something the publisher is
+        // billed for, so they always run under the service account.
+        const token = process.env.RIGOBOT_SYSTEM_TOKEN;
+        if (!token) {
+            await (0, publishJournal_1.markStage)(journalStorage, journal, "descriptions", "failed", {
+                error: "RIGOBOT_SYSTEM_TOKEN is not configured",
+            });
+            console.error(`[descriptions] Skipping stage for "${courseSlug}": RIGOBOT_SYSTEM_TOKEN is not configured`);
+            outcome = { generation: null, mirror: null, succeeded: false };
+            return outcome;
+        }
+        outcome = await runPublishDescriptionsStage({
+            courseSlug,
+            rigobotToken: token,
+            gcsBucket: params.gcsBucket,
+            journal,
+            journalStorage,
+            publishedStorage: publishedStorage(),
+            draftStorage: params.draftStorage,
+            generate: params.generate,
+        });
+        if (outcome.succeeded) {
+            console.log(`[descriptions] "${courseSlug}": ${(_b = (_a = outcome.generation) === null || _a === void 0 ? void 0 : _a.generated) !== null && _b !== void 0 ? _b : 0} description(s), ${(_d = (_c = outcome.mirror) === null || _c === void 0 ? void 0 : _c.copied) !== null && _d !== void 0 ? _d : 0} mirrored`);
+        }
+        else {
+            console.error(`[descriptions] "${courseSlug}": stage failed${((_e = outcome.generation) === null || _e === void 0 ? void 0 : _e.errors.length) ?
+                ` (${outcome.generation.errors.join("; ")})` :
+                ""}`);
+        }
+        return outcome;
+    }
+    catch (error) {
+        console.error(`[descriptions] Stage failed for "${courseSlug}":`, error.message);
+        outcome = { generation: null, mirror: null, succeeded: false };
+        return outcome;
+    }
+    finally {
+        // The contract: a publication that announced `descriptions: "queued"` is
+        // always followed by exactly one manifest event, success or failure.
+        // Emitting from `finally` is what makes "exactly one, on every exit path"
+        // true by construction rather than by remembering to call it.
+        if (params.hasWork) {
+            await emitManifestUpdated({
+                courseSlug,
+                journal,
+                journalStorage,
+                outcome,
+                eventContext: params.eventContext,
+                breathecodeToken: params.breathecodeToken,
+                publishedStorage: publishedStorage(),
+                emit: (_f = params.emit) !== null && _f !== void 0 ? _f : publishEvents_1.sendPublishEvent,
+            });
+        }
+        await (0, publishJournal_1.finalizeJournal)(journalStorage, journal);
+    }
+}
+async function emitManifestUpdated(params) {
+    var _a, _b, _c;
+    const { journal, journalStorage } = params;
+    if (!params.eventContext || !params.breathecodeToken) {
+        // Nothing was announced to breathecode, so nothing is owed.
+        await (0, publishJournal_1.markStage)(journalStorage, journal, "manifestEvent", "done", {
+            meta: { reason: "no_event_context" },
+        });
+        return;
+    }
+    // Enriching the payload must never prevent the delivery. The manifest is
+    // optional in the contract (`manifest: null` is valid); the event is not:
+    // breathecode was promised one and is waiting for it. Reading the manifest
+    // from the published bucket can fail for reasons that have nothing to do with
+    // the event — a bad AWS credential, say — and an event with less context still
+    // beats an event that never arrives.
+    let updatedManifest = params.eventContext.manifest;
+    try {
+        updatedManifest =
+            (_c = (await ((_b = (_a = params.publishedStorage).readManifest) === null || _b === void 0 ? void 0 : _b.call(_a, params.courseSlug)))) !== null && _c !== void 0 ? _c : params.eventContext.manifest;
+    }
+    catch (error) {
+        console.error(`[descriptions] Could not read the updated manifest for "${params.courseSlug}", reporting without it:`, error.message);
+    }
+    try {
+        const generation = params.outcome.generation;
+        const delivered = await params.emit((0, publishEvents_1.buildPackageManifestUpdatedEvent)(Object.assign(Object.assign({}, params.eventContext), { manifest: updatedManifest }), params.outcome.succeeded ? "success" : "failed", generation ?
+            {
+                generated: generation.generated,
+                failed: generation.failed,
+                missing: generation.missing,
+            } :
+            undefined), params.breathecodeToken);
+        await (0, publishJournal_1.markStage)(journalStorage, journal, "manifestEvent", delivered ? "done" : "failed", { error: delivered ? undefined : "delivery failed" });
+    }
+    catch (error) {
+        await (0, publishJournal_1.markStage)(journalStorage, journal, "manifestEvent", "failed", {
+            error: error.message,
+        });
+    }
+}

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

@@ -0,0 +1,36 @@
+import { JournalStorage, PublishJournal } from "../publishJournal";
+import { fetchPackageInfo, sendPublishEvent } from "../publishEvents";
+import { CourseDescriptionsStorage, GenerateCourseDescriptionsOptions } from "./generateCourseDescriptions";
+/**
+ * Recovery of a publication whose background stage never finished.
+ *
+ * The stage runs inside the web process, so a dyno restart mid-flight leaves a
+ * package published but not described, and — worse — breathecode waiting for a
+ * manifest event that was promised and will never arrive. Content-wise the
+ * missing descriptions would eventually be picked up by the next publication,
+ * but the promised event has no such second chance: emitting it is the reason
+ * this exists.
+ */
+export declare const MAX_SWEEP_ATTEMPTS = 3;
+/** Only resume publications nobody is working on any more. */
+export declare const DEFAULT_STALE_AFTER_MS: number;
+export type ResumeOutcome = "skipped-recent" | "skipped-abandoned" | "abandoned" | "resumed" | "nothing-to-do";
+export type ResumeDeps = {
+    journalStorage: JournalStorage;
+    publishedStorage: CourseDescriptionsStorage;
+    draftStorage: CourseDescriptionsStorage;
+    rigobotToken: string;
+    breathecodeToken?: string;
+    staleAfterMs?: number;
+    now?: number;
+    /** Injection points for tests. */
+    emit?: typeof sendPublishEvent;
+    readPackageInfo?: typeof fetchPackageInfo;
+    generate?: GenerateCourseDescriptionsOptions["generate"];
+};
+/**
+ * Whether breathecode is still owed a manifest event: one was promised (the
+ * publish event announced `queued`) and it never went out.
+ */
+export declare function owesManifestEvent(journal: PublishJournal): boolean;
+export declare function resumePublication(journal: PublishJournal, deps: ResumeDeps): Promise<ResumeOutcome>;

package/lib/utils/descriptions/resumePublication.js

@@ -0,0 +1,128 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_STALE_AFTER_MS = exports.MAX_SWEEP_ATTEMPTS = void 0;
+exports.owesManifestEvent = owesManifestEvent;
+exports.resumePublication = resumePublication;
+const publishJournal_1 = require("../publishJournal");
+const publishEvents_1 = require("../publishEvents");
+const publishStage_1 = require("./publishStage");
+/**
+ * Recovery of a publication whose background stage never finished.
+ *
+ * The stage runs inside the web process, so a dyno restart mid-flight leaves a
+ * package published but not described, and — worse — breathecode waiting for a
+ * manifest event that was promised and will never arrive. Content-wise the
+ * missing descriptions would eventually be picked up by the next publication,
+ * but the promised event has no such second chance: emitting it is the reason
+ * this exists.
+ */
+exports.MAX_SWEEP_ATTEMPTS = 3;
+/** Only resume publications nobody is working on any more. */
+exports.DEFAULT_STALE_AFTER_MS = 15 * 60 * 1000;
+function isDone(journal, stage) {
+    return journal.stages[stage].status === "done";
+}
+/**
+ * Whether breathecode is still owed a manifest event: one was promised (the
+ * publish event announced `queued`) and it never went out.
+ */
+function owesManifestEvent(journal) {
+    var _a;
+    const promised = ((_a = journal.stages.publishedEvent.meta) === null || _a === void 0 ? void 0 : _a.descriptions) === "queued";
+    return promised && !isDone(journal, "manifestEvent");
+}
+async function resumePublication(journal, deps) {
+    var _a, _b;
+    const { journalStorage } = deps;
+    const now = (_a = deps.now) !== null && _a !== void 0 ? _a : Date.now();
+    if (journal.abandoned) {
+        return "skipped-abandoned";
+    }
+    // A publication still in flight would race with its own stage.
+    if (!(0, publishJournal_1.isJournalStale)(journal, (_b = deps.staleAfterMs) !== null && _b !== void 0 ? _b : exports.DEFAULT_STALE_AFTER_MS, now)) {
+        return "skipped-recent";
+    }
+    const needsDescriptions = !isDone(journal, "descriptions") || !isDone(journal, "gcsMirror");
+    const needsEvent = owesManifestEvent(journal);
+    if (!needsDescriptions && !needsEvent) {
+        // Nothing left that the sweep can do; stage A failures are not its job.
+        await (0, publishJournal_1.finalizeJournal)(journalStorage, journal);
+        return "nothing-to-do";
+    }
+    if (journal.attempts >= exports.MAX_SWEEP_ATTEMPTS) {
+        await (0, publishJournal_1.abandonJournal)(journalStorage, journal);
+        console.error(`[sweep] Giving up on "${journal.courseSlug}" (${journal.publishId}) after ${journal.attempts} attempts`);
+        return "abandoned";
+    }
+    await (0, publishJournal_1.incrementAttempts)(journalStorage, journal);
+    let succeeded = true;
+    let stats;
+    if (needsDescriptions) {
+        const outcome = await (0, publishStage_1.runPublishDescriptionsStage)({
+            courseSlug: journal.courseSlug,
+            rigobotToken: deps.rigobotToken,
+            journal,
+            journalStorage,
+            publishedStorage: deps.publishedStorage,
+            draftStorage: deps.draftStorage,
+            generate: deps.generate,
+        });
+        succeeded = outcome.succeeded;
+        if (outcome.generation) {
+            stats = {
+                generated: outcome.generation.generated,
+                failed: outcome.generation.failed,
+                missing: outcome.generation.missing,
+            };
+        }
+    }
+    if (needsEvent) {
+        await emitPendingManifestEvent(journal, deps, succeeded, stats);
+    }
+    await (0, publishJournal_1.finalizeJournal)(journalStorage, journal);
+    return "resumed";
+}
+async function emitPendingManifestEvent(journal, deps, succeeded, stats) {
+    var _a, _b;
+    const emit = (_a = deps.emit) !== null && _a !== void 0 ? _a : publishEvents_1.sendPublishEvent;
+    const readPackageInfo = (_b = deps.readPackageInfo) !== null && _b !== void 0 ? _b : publishEvents_1.fetchPackageInfo;
+    if (!deps.breathecodeToken) {
+        await (0, publishJournal_1.markStage)(deps.journalStorage, journal, "manifestEvent", "failed", {
+            error: "BREATHECODE_SYSTEM_TOKEN is not configured",
+        });
+        return;
+    }
+    // Enriching the payload must never prevent the delivery: this event is the
+    // one breathecode has been waiting for since the publication stalled, and
+    // both the manifest and the package info are optional in the contract.
+    let manifest = null;
+    let packageInfo = null;
+    try {
+        if (deps.publishedStorage.readManifest) {
+            manifest = await deps.publishedStorage.readManifest(journal.courseSlug);
+        }
+    }
+    catch (error) {
+        console.error(`[sweep] Could not read the manifest of "${journal.courseSlug}", reporting without it:`, error.message);
+    }
+    try {
+        packageInfo = await readPackageInfo(journal.courseSlug, deps.rigobotToken);
+    }
+    catch (error) {
+        console.error(`[sweep] Could not read the package of "${journal.courseSlug}", reporting without it:`, error.message);
+    }
+    try {
+        const delivered = await emit((0, publishEvents_1.buildPackageManifestUpdatedEvent)({
+            publishId: journal.publishId,
+            courseSlug: journal.courseSlug,
+            packageInfo,
+            manifest,
+        }, succeeded ? "success" : "failed", stats), deps.breathecodeToken);
+        await (0, publishJournal_1.markStage)(deps.journalStorage, journal, "manifestEvent", delivered ? "done" : "failed", { error: delivered ? undefined : "delivery failed" });
+    }
+    catch (error) {
+        await (0, publishJournal_1.markStage)(deps.journalStorage, journal, "manifestEvent", "failed", {
+            error: error.message,
+        });
+    }
+}

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

@@ -0,0 +1,30 @@
+import { AwsClient } from "../s3/packageManifestBackfill";
+import { SyllabusSyncStorage } from "../syllabusSync";
+import { CourseDescriptionsStorage } from "./generateCourseDescriptions";
+import { CourseExercise } from "./workList";
+/**
+ * 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.
+ */
+export declare const syllabusKey: (slug: string) => string;
+export declare const manifestKey: (slug: string) => string;
+export declare function fetchExercises(s3: AwsClient, bucket: string, slug: string): Promise<CourseExercise[]>;
+export declare function createS3SyllabusSyncStorage(s3: AwsClient, bucket: string): SyllabusSyncStorage;
+export type S3DescriptionsStorageOptions = {
+    /** CloudFront distribution to invalidate after re-projecting the manifest. */
+    cloudFront?: {
+        client: AwsClient;
+        distributionId: string;
+    };
+    /** Set false in the backfill, where manifests are projected in a later pass. */
+    reprojectManifest?: boolean;
+};
+/**
+ * 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.
+ */
+export declare function createS3DescriptionsStorageFromEnv(): CourseDescriptionsStorage;
+export declare function createS3DescriptionsStorage(s3: AwsClient, bucket: string, options?: S3DescriptionsStorageOptions): CourseDescriptionsStorage;