@learnpack/learnpack 5.0.352 → 5.0.353

package/lib/utils/descriptions/publishStage.js

@@ -0,0 +1,234 @@
+"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;
+    }
+    try {
+        // Report the manifest as it is NOW: the descriptions are the whole point of
+        // this event, so the one captured at publish time would be stale.
+        const 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;
+        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,113 @@
+"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;
+    }
+    try {
+        let manifest = null;
+        if (deps.publishedStorage.readManifest) {
+            manifest = await deps.publishedStorage.readManifest(journal.courseSlug);
+        }
+        const delivered = await emit((0, publishEvents_1.buildPackageManifestUpdatedEvent)({
+            publishId: journal.publishId,
+            courseSlug: journal.courseSlug,
+            packageInfo: await readPackageInfo(journal.courseSlug, deps.rigobotToken),
+            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;

package/lib/utils/descriptions/s3Storage.js

@@ -0,0 +1,134 @@
+"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");
+/**
+ * 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() {
+    const s3 = new client_s3_1.S3Client({
+        region: process.env.AWS_REGION || "us-east-1",
+    });
+    const distributionId = process.env.CLOUDFRONT_DISTRIBUTION_ID;
+    const cloudFront = distributionId ?
+        {
+            client: new client_cloudfront_1.CloudFrontClient({
+                region: process.env.AWS_REGION || "us-east-1",
+            }),
+            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, process.env.S3_PACKAGES_BUCKET || "learnpack-paquetes", { 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;