@learnpack/learnpack 5.0.352 → 5.0.354

package/lib/utils/descriptionHash.js

@@ -0,0 +1,173 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.stripMarkdownImages = stripMarkdownImages;
+exports.normalizeReadme = normalizeReadme;
+exports.sha256 = sha256;
+exports.simhash64 = simhash64;
+exports.hammingHex = hammingHex;
+exports.fingerprintReadme = fingerprintReadme;
+exports.getSimhashThreshold = getSimhashThreshold;
+exports.isDescriptionStale = isDescriptionStale;
+const crypto = require("crypto");
+// eslint-disable-next-line @typescript-eslint/no-var-requires
+const frontMatter = require("front-matter");
+/**
+ * Utilities to detect whether a step description is stale relative to its
+ * README content.
+ *
+ * Two signals are stored per (step, lang) at generation time:
+ *  - sha256(normalizeReadme(content))  -> exact fast-path + content-addressing
+ *  - simhash64(normalizeReadme(content)) -> near-duplicate significance filter
+ *
+ * The sweep re-hashes the current README and compares against the stored
+ * values: exact SHA-256 match => no-op; otherwise if the SimHash Hamming
+ * distance to the *generation baseline* is <= k the change is cosmetic and is
+ * ignored, else the description is regenerated. The H1 title is part of the
+ * normalized content (a deliberate product decision).
+ */
+/**
+ * Remove every image from markdown: inline `![alt](url)`, reference-style
+ * `![alt][ref]` and raw `<img>` tags. Regular links `[text](url)` are kept.
+ *
+ * Images are dropped from BOTH sides of the description pipeline — here for
+ * fingerprinting, and again before sending the README to the LLM. Adding,
+ * replacing or removing an illustration does not change what the lesson
+ * teaches, so it must not trigger a regeneration; and the alt text of generated
+ * illustrations is a full image-generation prompt (hundreds of tokens) that
+ * only invites the model to describe the picture instead of the lesson.
+ *
+ * Note the alt text may legitimately contain parentheses, so the alt is matched
+ * as "anything up to the closing bracket" rather than as balanced text.
+ */
+function stripMarkdownImages(content) {
+    return (content
+        // ![alt](url) — alt may span lines and contain parentheses
+        .replace(/!\[[^\]]*]\([^)]*\)/g, "")
+        // ![alt][ref] — i.e. `!` followed by two bracketed groups
+        .replace(/!(?:\[[^\]]*]){2}/g, "")
+        // <img ...> / <img ... />
+        .replace(/<img\b[^>]*>/gi, "")
+        // [](url) left behind by linked images such as badges
+        .replace(/\[\s*]\([^)]*\)/g, ""));
+}
+/**
+ * Canonicalize a README for hashing. Strips the frontmatter (metadata such as
+ * tutorial/intro video URLs, which do not describe the lesson), removes images
+ * (see `stripMarkdownImages`) and collapses all whitespace runs so that
+ * reformatting, blank lines and trailing spaces do not register as content
+ * changes. The H1 and the prose are preserved.
+ */
+function normalizeReadme(content) {
+    let body = content;
+    try {
+        const parsed = frontMatter(content);
+        body = typeof parsed.body === "string" ? parsed.body : content;
+    }
+    catch (_a) {
+        body = content;
+    }
+    return stripMarkdownImages(body)
+        .replace(/\r/g, "")
+        .replace(/\s+/g, " ")
+        .trim();
+}
+function sha256(input) {
+    return crypto.createHash("sha256").update(input).digest("hex");
+}
+// The build targets < ES2020, so BigInt literals are unavailable. The 64-bit
+// SimHash is therefore represented as two unsigned 32-bit halves { hi, lo } and
+// serialized as a 16-char hex string (hi then lo).
+function toHex32(x) {
+    return (x >>> 0).toString(16).padStart(8, "0");
+}
+function popcount32(input) {
+    let x = input >>> 0;
+    let count = 0;
+    while (x !== 0) {
+        count += x & 1;
+        x >>>= 1;
+    }
+    return count;
+}
+function hashToken64(token) {
+    // First 8 bytes (16 hex chars) of an md5 digest -> two 32-bit halves.
+    const hex = crypto.createHash("md5").update(token).digest("hex").slice(0, 16);
+    return {
+        hi: Number.parseInt(hex.slice(0, 8), 16) >>> 0,
+        lo: Number.parseInt(hex.slice(8, 16), 16) >>> 0,
+    };
+}
+/**
+ * 64-bit SimHash (Charikar) over whitespace-delimited tokens, returned as a
+ * zero-padded 16-char hex string.
+ */
+function simhash64(input) {
+    const tokens = input.split(/\s+/).filter(Boolean);
+    if (tokens.length === 0) {
+        return "0".repeat(16);
+    }
+    const weights = Array.from({ length: 64 }, () => 0);
+    for (const token of tokens) {
+        const { hi, lo } = hashToken64(token);
+        for (let i = 0; i < 32; i++) {
+            weights[i] += ((lo >>> i) & 1) === 1 ? 1 : -1;
+            weights[32 + i] += ((hi >>> i) & 1) === 1 ? 1 : -1;
+        }
+    }
+    let lo = 0;
+    let hi = 0;
+    for (let i = 0; i < 32; i++) {
+        if (weights[i] > 0) {
+            lo |= 1 << i;
+        }
+        if (weights[32 + i] > 0) {
+            hi |= 1 << i;
+        }
+    }
+    return toHex32(hi) + toHex32(lo);
+}
+/** Hamming distance between two 64-bit hex fingerprints. */
+function hammingHex(a, b) {
+    const hiA = Number.parseInt(a.slice(0, 8), 16) >>> 0;
+    const loA = Number.parseInt(a.slice(8, 16), 16) >>> 0;
+    const hiB = Number.parseInt(b.slice(0, 8), 16) >>> 0;
+    const loB = Number.parseInt(b.slice(8, 16), 16) >>> 0;
+    return popcount32((hiA ^ hiB) >>> 0) + popcount32((loA ^ loB) >>> 0);
+}
+/** Convenience: normalize + both fingerprints in one call. */
+function fingerprintReadme(content) {
+    const normalized = normalizeReadme(content);
+    return {
+        sha256: sha256(normalized),
+        simhash: simhash64(normalized),
+    };
+}
+/**
+ * Default significance threshold (Hamming distance over the 64-bit SimHash).
+ * k=3 is the classic near-duplicate threshold for 64-bit SimHash
+ * (Charikar 2002; Manku, Jain & Das Sarma, WWW 2007). Overridable via env.
+ */
+function getSimhashThreshold() {
+    const raw = process.env.DESCRIPTION_SIMHASH_THRESHOLD;
+    const parsed = raw ? Number.parseInt(raw, 10) : Number.NaN;
+    return Number.isFinite(parsed) && parsed >= 0 ? parsed : 3;
+}
+/**
+ * Decide whether a description generated from `previous` is stale given the
+ * `current` README content. Exact match => not stale; else stale only if the
+ * SimHash Hamming distance exceeds the threshold (cosmetic edits are ignored).
+ */
+function isDescriptionStale(previous, current, threshold = getSimhashThreshold()) {
+    if (!previous || !previous.sha256) {
+        // Never generated -> treat as needing generation (i.e. "stale").
+        return true;
+    }
+    if (previous.sha256 === current.sha256) {
+        return false;
+    }
+    if (!previous.simhash) {
+        // No baseline fingerprint to compare against -> be conservative.
+        return true;
+    }
+    return hammingHex(previous.simhash, current.simhash) > threshold;
+}

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

@@ -0,0 +1,60 @@
+import { fetchPackageInfo, sendPublishEvent } from "../publishEvents";
+import { CourseDescriptionsStorage, GenerateCourseDescriptionsResult } from "./generateCourseDescriptions";
+/**
+ * `package_manifest_updated` for courses reconciled by the backfill.
+ *
+ * The backfill regenerates descriptions of packages that are already published,
+ * so breathecode needs the same notification a publication sends — but there is
+ * no publication here: no `package_published` precedes this event, and no
+ * journal tracks it (the sweep resumes publications, and a backfill is simply
+ * re-run instead).
+ *
+ * That is what makes `publish_id` awkward. The field exists to correlate the two
+ * events of one publication, a pair this event has no half of. Since it is
+ * required, the value has to be something that cannot be mistaken for a real
+ * publication: a bare uuid — the obvious choice — would be exactly that mistake,
+ * and if breathecode ever starts pairing events it would search forever for a
+ * `package_published` that was never sent.
+ *
+ * Hence `backfill-{runId}-{slug}`:
+ *
+ * - the `backfill-` prefix makes the origin readable in the webhook log and
+ *   discriminable in code (`isBackfillPublishId`); real ids are bare uuids from
+ *   `createJournal`, so the two spaces cannot collide;
+ * - `{slug}` keeps it unique per event, which a per-run id alone would not be;
+ * - a `{runId}` shared by every course of one invocation makes "every event from
+ *   the run I fired at 15:40" a single substring query, which is the question
+ *   you actually ask when the catalogue is backfilled in small batches.
+ *
+ * Encoding this in `publish_id`, rather than adding an `origin` field, keeps the
+ * event contract untouched: breathecode ignores `publish_id` today, so this
+ * costs them nothing and needs no coordination. If they ever start consuming the
+ * provenance, it can be promoted to a field of its own.
+ */
+export declare const BACKFILL_PUBLISH_ID_PREFIX = "backfill-";
+/** One per script invocation, shared by every course it touches. */
+export declare function newBackfillRunId(): string;
+export declare function backfillPublishId(runId: string, courseSlug: string): string;
+export declare function isBackfillPublishId(publishId: string): boolean;
+/**
+ * `skipped` means the event was never attempted, which is not a failure: a
+ * course the backfill did not change has nothing to announce.
+ */
+export type BackfillEventOutcome = "skipped" | "delivered" | "failed";
+export type EmitBackfillManifestEventParams = {
+    courseSlug: string;
+    runId: string;
+    result: GenerateCourseDescriptionsResult;
+    storage: CourseDescriptionsStorage;
+    rigobotToken: string;
+    breathecodeToken: string;
+    /** Injection points for tests. */
+    emit?: typeof sendPublishEvent;
+    readPackageInfo?: typeof fetchPackageInfo;
+};
+/**
+ * Announce one reconciled course. Never throws: the descriptions and the
+ * manifest are already written by the time this runs, and losing the
+ * notification must not turn a successful course into a failed one.
+ */
+export declare function emitBackfillManifestEvent(params: EmitBackfillManifestEventParams): Promise<BackfillEventOutcome>;

package/lib/utils/descriptions/backfillEvents.js

@@ -0,0 +1,107 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BACKFILL_PUBLISH_ID_PREFIX = void 0;
+exports.newBackfillRunId = newBackfillRunId;
+exports.backfillPublishId = backfillPublishId;
+exports.isBackfillPublishId = isBackfillPublishId;
+exports.emitBackfillManifestEvent = emitBackfillManifestEvent;
+const uuid_1 = require("uuid");
+const publishEvents_1 = require("../publishEvents");
+/**
+ * `package_manifest_updated` for courses reconciled by the backfill.
+ *
+ * The backfill regenerates descriptions of packages that are already published,
+ * so breathecode needs the same notification a publication sends — but there is
+ * no publication here: no `package_published` precedes this event, and no
+ * journal tracks it (the sweep resumes publications, and a backfill is simply
+ * re-run instead).
+ *
+ * That is what makes `publish_id` awkward. The field exists to correlate the two
+ * events of one publication, a pair this event has no half of. Since it is
+ * required, the value has to be something that cannot be mistaken for a real
+ * publication: a bare uuid — the obvious choice — would be exactly that mistake,
+ * and if breathecode ever starts pairing events it would search forever for a
+ * `package_published` that was never sent.
+ *
+ * Hence `backfill-{runId}-{slug}`:
+ *
+ * - the `backfill-` prefix makes the origin readable in the webhook log and
+ *   discriminable in code (`isBackfillPublishId`); real ids are bare uuids from
+ *   `createJournal`, so the two spaces cannot collide;
+ * - `{slug}` keeps it unique per event, which a per-run id alone would not be;
+ * - a `{runId}` shared by every course of one invocation makes "every event from
+ *   the run I fired at 15:40" a single substring query, which is the question
+ *   you actually ask when the catalogue is backfilled in small batches.
+ *
+ * Encoding this in `publish_id`, rather than adding an `origin` field, keeps the
+ * event contract untouched: breathecode ignores `publish_id` today, so this
+ * costs them nothing and needs no coordination. If they ever start consuming the
+ * provenance, it can be promoted to a field of its own.
+ */
+exports.BACKFILL_PUBLISH_ID_PREFIX = "backfill-";
+/** One per script invocation, shared by every course it touches. */
+function newBackfillRunId() {
+    return (0, uuid_1.v4)();
+}
+function backfillPublishId(runId, courseSlug) {
+    return `${exports.BACKFILL_PUBLISH_ID_PREFIX}${runId}-${courseSlug}`;
+}
+function isBackfillPublishId(publishId) {
+    return publishId.startsWith(exports.BACKFILL_PUBLISH_ID_PREFIX);
+}
+/**
+ * Announce one reconciled course. Never throws: the descriptions and the
+ * manifest are already written by the time this runs, and losing the
+ * notification must not turn a successful course into a failed one.
+ */
+async function emitBackfillManifestEvent(params) {
+    var _a, _b;
+    const { courseSlug, result } = params;
+    if (result.status === "skipped") {
+        return "skipped";
+    }
+    const emit = (_a = params.emit) !== null && _a !== void 0 ? _a : publishEvents_1.sendPublishEvent;
+    const readPackageInfo = (_b = params.readPackageInfo) !== null && _b !== void 0 ? _b : publishEvents_1.fetchPackageInfo;
+    // Enriching the payload must never prevent the delivery: both the manifest and
+    // the package info are optional in the contract, and an event with less
+    // context beats an event that never arrives.
+    let manifest = null;
+    try {
+        if (params.storage.readManifest) {
+            manifest = await params.storage.readManifest(courseSlug);
+        }
+    }
+    catch (error) {
+        console.error(`[backfill-events] Could not read the manifest of "${courseSlug}", reporting without it:`, error.message);
+    }
+    let packageInfo = null;
+    try {
+        packageInfo = await readPackageInfo(courseSlug, params.rigobotToken);
+    }
+    catch (error) {
+        console.error(`[backfill-events] Could not read the package "${courseSlug}", reporting without it:`, error.message);
+    }
+    try {
+        const delivered = await emit((0, publishEvents_1.buildPackageManifestUpdatedEvent)({
+            publishId: backfillPublishId(params.runId, courseSlug),
+            courseSlug,
+            packageInfo,
+            manifest,
+        }, 
+        // A failed projection does not fail the run — the syllabus is saved
+        // either way — but this event reports the manifest, so it cannot claim
+        // success over one that was never rewritten.
+        result.status === "failed" || result.manifestProjected === false ?
+            "failed" :
+            "success", {
+            generated: result.generated,
+            failed: result.failed,
+            missing: result.missing,
+        }), params.breathecodeToken);
+        return delivered ? "delivered" : "failed";
+    }
+    catch (error) {
+        console.error(`[backfill-events] Could not deliver the manifest event for "${courseSlug}":`, error.message);
+        return "failed";
+    }
+}

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

@@ -0,0 +1,16 @@
+import { Bucket } from "@google-cloud/storage";
+import { CourseDescriptionsStorage } from "./generateCourseDescriptions";
+/**
+ * Draft-bucket (GCS) adapter.
+ *
+ * Descriptions are never generated against this bucket — it keeps moving while
+ * the teacher edits, so it is not a stable snapshot. It is only written by the
+ * mirror-back, which copies descriptions generated from the published package
+ * whenever the draft content still matches.
+ *
+ * Note there is no `reprojectManifest`: the manifest is only rebuilt when
+ * publishing.
+ */
+export declare const gcsSyllabusPath: (courseSlug: string) => string;
+export declare const gcsReadmePath: (courseSlug: string, exerciseSlug: string, fileName: string) => string;
+export declare function createGcsDescriptionsStorage(bucket: Bucket): CourseDescriptionsStorage;

package/lib/utils/descriptions/gcsStorage.js

@@ -0,0 +1,60 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.gcsReadmePath = exports.gcsSyllabusPath = void 0;
+exports.createGcsDescriptionsStorage = createGcsDescriptionsStorage;
+const configBuilder_1 = require("../configBuilder");
+const syllabusSync_1 = require("../syllabusSync");
+/**
+ * Draft-bucket (GCS) adapter.
+ *
+ * Descriptions are never generated against this bucket — it keeps moving while
+ * the teacher edits, so it is not a stable snapshot. It is only written by the
+ * mirror-back, which copies descriptions generated from the published package
+ * whenever the draft content still matches.
+ *
+ * Note there is no `reprojectManifest`: the manifest is only rebuilt when
+ * publishing.
+ */
+const gcsSyllabusPath = (courseSlug) => `courses/${courseSlug}/.learn/initialSyllabus.json`;
+exports.gcsSyllabusPath = gcsSyllabusPath;
+const gcsReadmePath = (courseSlug, exerciseSlug, fileName) => `courses/${courseSlug}/exercises/${exerciseSlug}/${fileName}`;
+exports.gcsReadmePath = gcsReadmePath;
+function createGcsDescriptionsStorage(bucket) {
+    return {
+        async readSyllabus(courseSlug) {
+            try {
+                const [buf] = await bucket.file((0, exports.gcsSyllabusPath)(courseSlug)).download();
+                return JSON.parse(buf.toString());
+            }
+            catch (_a) {
+                return null;
+            }
+        },
+        async writeSyllabus(courseSlug, syllabus) {
+            await bucket
+                .file((0, exports.gcsSyllabusPath)(courseSlug))
+                .save(Buffer.from(JSON.stringify(syllabus), "utf8"), {
+                contentType: "application/json",
+            });
+        },
+        async listExercises(courseSlug) {
+            const { exercises } = await (0, configBuilder_1.buildConfig)(bucket, courseSlug);
+            return exercises.map(exercise => ({
+                slug: exercise.slug,
+                translations: exercise.translations || {},
+            }));
+        },
+        async readReadme(courseSlug, exerciseSlug, fileName) {
+            try {
+                const [buf] = await bucket
+                    .file((0, exports.gcsReadmePath)(courseSlug, exerciseSlug, fileName))
+                    .download();
+                return buf.toString();
+            }
+            catch (_a) {
+                return null;
+            }
+        },
+        syllabusSyncStorage: (0, syllabusSync_1.createGcsSyllabusSyncStorage)(bucket),
+    };
+}

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

@@ -0,0 +1,66 @@
+import { Syllabus } from "../../models/creator";
+import { PackageManifest } from "../packageManifest";
+import { TGenerateStepDescriptionsParams, TGenerateStepDescriptionsResult } from "../rigoActions";
+import { SyllabusSyncStorage } from "../syllabusSync";
+import { CourseExercise, CourseReadmes } from "./workList";
+/**
+ * Generate and persist the step descriptions of one published course.
+ *
+ * This is the single implementation behind every flow that produces
+ * descriptions: the background stage that runs after publishing, the sweep that
+ * recovers interrupted publications, and the one-off backfill over the
+ * historical catalogue. They differ only in what triggers them.
+ *
+ * Storage is a port so the service can be driven against the published bucket
+ * (the real case) or an in-memory double (tests), and so the manifest
+ * re-projection stays where the storage-specific knowledge lives.
+ */
+export declare const DEFAULT_DESCRIPTIONS_CONCURRENCY = 5;
+export interface CourseDescriptionsStorage {
+    readSyllabus(courseSlug: string): Promise<Syllabus | null>;
+    writeSyllabus(courseSlug: string, syllabus: Syllabus): Promise<void>;
+    listExercises(courseSlug: string): Promise<CourseExercise[]>;
+    readReadme(courseSlug: string, exerciseSlug: string, fileName: string): Promise<string | null>;
+    /** Re-generate `package-manifest.json` from the syllabus and invalidate the CDN. */
+    reprojectManifest?(courseSlug: string): Promise<void>;
+    /** Read the stored manifest, to report the updated one in the event. */
+    readManifest?(courseSlug: string): Promise<PackageManifest | null>;
+    /** Enables the provisional additive syllabus reconciliation. */
+    syllabusSyncStorage?: SyllabusSyncStorage;
+}
+export type GenerateCourseDescriptionsOptions = {
+    token: string;
+    dryRun?: boolean;
+    force?: boolean;
+    concurrency?: number;
+    targetWordCount?: number;
+    promptVersion?: number;
+    /** Additive syllabus reconciliation before computing the work list. */
+    reconcile?: boolean;
+    /** Injection point for tests. */
+    generate?: (token: string, params: TGenerateStepDescriptionsParams) => Promise<TGenerateStepDescriptionsResult | null>;
+};
+export type GenerateCourseDescriptionsResult = {
+    /** `skipped` means there was nothing to do, not that something went wrong. */
+    status: "skipped" | "processed" | "failed";
+    steps: number;
+    /** (step, language) pairs written. */
+    generated: number;
+    /** Steps whose completion failed outright. */
+    failed: number;
+    /** (step, language) pairs the model never answered; retried later. */
+    missing: number;
+    errors: string[];
+    /** Completion durations, to watch how close we run to the request limits. */
+    durationsSeconds: number[];
+    /**
+     * Whether `package-manifest.json` was re-projected; null when the storage does
+     * not project at all. A failed projection is not a failed run — the syllabus,
+     * which is the source of truth, is already saved — but callers that announce
+     * the manifest downstream must not report success on it.
+     */
+    manifestProjected: boolean | null;
+};
+/** Read every README of the course, keyed by exercise slug and language. */
+export declare function readCourseReadmes(storage: CourseDescriptionsStorage, courseSlug: string, exercises: CourseExercise[], concurrency: number): Promise<CourseReadmes>;
+export declare function generateCourseDescriptions(storage: CourseDescriptionsStorage, courseSlug: string, options: GenerateCourseDescriptionsOptions): Promise<GenerateCourseDescriptionsResult>;

package/lib/utils/descriptions/generateCourseDescriptions.js

@@ -0,0 +1,176 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_DESCRIPTIONS_CONCURRENCY = void 0;
+exports.readCourseReadmes = readCourseReadmes;
+exports.generateCourseDescriptions = generateCourseDescriptions;
+const rigoActions_1 = require("../rigoActions");
+const packageManifestBackfill_1 = require("../s3/packageManifestBackfill");
+const syllabusSync_1 = require("../syllabusSync");
+const workList_1 = require("./workList");
+/**
+ * Generate and persist the step descriptions of one published course.
+ *
+ * This is the single implementation behind every flow that produces
+ * descriptions: the background stage that runs after publishing, the sweep that
+ * recovers interrupted publications, and the one-off backfill over the
+ * historical catalogue. They differ only in what triggers them.
+ *
+ * Storage is a port so the service can be driven against the published bucket
+ * (the real case) or an in-memory double (tests), and so the manifest
+ * re-projection stays where the storage-specific knowledge lives.
+ */
+exports.DEFAULT_DESCRIPTIONS_CONCURRENCY = 5;
+function emptyResult(status) {
+    return {
+        status,
+        steps: 0,
+        generated: 0,
+        failed: 0,
+        missing: 0,
+        errors: [],
+        durationsSeconds: [],
+        manifestProjected: null,
+    };
+}
+/** Read every README of the course, keyed by exercise slug and language. */
+async function readCourseReadmes(storage, courseSlug, exercises, concurrency) {
+    const readmes = {};
+    const targets = [];
+    for (const exercise of exercises) {
+        for (const [lang, file] of Object.entries(exercise.translations || {})) {
+            targets.push({ exerciseSlug: exercise.slug, lang, file });
+        }
+    }
+    const contents = await (0, packageManifestBackfill_1.mapWithConcurrency)(targets, concurrency, target => storage.readReadme(courseSlug, target.exerciseSlug, target.file));
+    for (const [index, target] of targets.entries()) {
+        const content = contents[index];
+        if (typeof content !== "string") {
+            continue;
+        }
+        if (!readmes[target.exerciseSlug]) {
+            readmes[target.exerciseSlug] = {};
+        }
+        readmes[target.exerciseSlug][target.lang] = content;
+    }
+    return readmes;
+}
+/** Ensure the translation slot exists before writing a description into it. */
+function ensureSlot(lesson, lang) {
+    if (!lesson.translations) {
+        lesson.translations = {};
+    }
+    if (!lesson.translations[lang]) {
+        lesson.translations[lang] = { completionId: 0, startedAt: Date.now() };
+    }
+    return lesson.translations[lang];
+}
+function applyStepResult(step, result) {
+    let generated = 0;
+    for (const language of step.languages) {
+        if (!(language.lang in result.descriptionsByLanguage)) {
+            // Never answered: leave the slot untouched so a later run retries it.
+            // Writing a null plus a fingerprint here would look settled forever.
+            continue;
+        }
+        const slot = ensureSlot(step.lesson, language.lang);
+        if (slot.descriptionSource === "human") {
+            continue;
+        }
+        const description = result.descriptionsByLanguage[language.lang];
+        slot.description = description;
+        slot.descriptionStatus = description ? "generated" : "none";
+        slot.descriptionSource = "auto";
+        slot.descriptionPromptVersion = result.promptVersion;
+        slot.sourceContentHash = language.fingerprint.sha256;
+        slot.sourceSimHash = language.fingerprint.simhash;
+        generated += 1;
+    }
+    return { generated, missing: result.missingLanguages.length };
+}
+async function generateCourseDescriptions(storage, courseSlug, options) {
+    var _a, _b;
+    const concurrency = (_a = options.concurrency) !== null && _a !== void 0 ? _a : exports.DEFAULT_DESCRIPTIONS_CONCURRENCY;
+    const generate = (_b = options.generate) !== null && _b !== void 0 ? _b : rigoActions_1.generateStepDescriptions;
+    const syllabus = await storage.readSyllabus(courseSlug);
+    if (!syllabus) {
+        return emptyResult("skipped");
+    }
+    const exercises = await storage.listExercises(courseSlug);
+    if (exercises.length === 0) {
+        return emptyResult("skipped");
+    }
+    if (options.reconcile && storage.syllabusSyncStorage) {
+        try {
+            await (0, syllabusSync_1.synchronizeSyllabusWithBucket)(storage.syllabusSyncStorage, courseSlug, syllabus, { prune: false });
+        }
+        catch (error) {
+            // Provisional patch: never let reconciliation block generation.
+            console.error(`[descriptions] Reconciliation failed for "${courseSlug}":`, error.message);
+        }
+    }
+    const readmes = await readCourseReadmes(storage, courseSlug, exercises, concurrency);
+    const work = (0, workList_1.buildDescriptionWorkList)({
+        syllabus,
+        exercises,
+        readmes,
+        promptVersion: options.promptVersion,
+        force: options.force,
+    });
+    if (work.length === 0) {
+        return emptyResult("skipped");
+    }
+    const result = emptyResult("processed");
+    result.steps = work.length;
+    if (options.dryRun) {
+        result.generated = (0, workList_1.countWorkItems)(work);
+        return result;
+    }
+    // One completion per step, several in flight: a slow step never stalls the
+    // course and Rigobot is never hit with an unbounded burst.
+    const outcomes = await (0, packageManifestBackfill_1.mapWithConcurrency)(work, concurrency, async (step) => {
+        var _a;
+        return ({
+            step,
+            generated: await generate(options.token, {
+                readmeContent: step.baseContent,
+                sourceLanguage: step.baseLanguage,
+                outputLanguages: step.languages.map(language => language.lang),
+                lessonTitle: step.lesson.title,
+                courseTitle: (_a = syllabus.courseInfo) === null || _a === void 0 ? void 0 : _a.title,
+                targetWordCount: options.targetWordCount,
+                promptVersion: options.promptVersion,
+            }),
+        });
+    });
+    for (const outcome of outcomes) {
+        if (!outcome.generated) {
+            result.failed += 1;
+            result.errors.push(`generation failed for "${outcome.step.exerciseSlug}"`);
+            continue;
+        }
+        if (outcome.generated.durationSeconds !== null) {
+            result.durationsSeconds.push(outcome.generated.durationSeconds);
+        }
+        const applied = applyStepResult(outcome.step, outcome.generated);
+        result.generated += applied.generated;
+        result.missing += applied.missing;
+    }
+    if (result.generated === 0 && result.failed > 0) {
+        result.status = "failed";
+        return result;
+    }
+    await storage.writeSyllabus(courseSlug, syllabus);
+    if (storage.reprojectManifest) {
+        try {
+            await storage.reprojectManifest(courseSlug);
+            result.manifestProjected = true;
+        }
+        catch (error) {
+            // The syllabus (the source of truth) is already saved; a failed
+            // projection is recoverable and must not lose the generated text.
+            result.manifestProjected = false;
+            result.errors.push(`manifest projection failed: ${error.message}`);
+        }
+    }
+    return result;
+}