@learnpack/learnpack 5.0.352 → 5.0.353

package/lib/utils/descriptions/workList.js

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

package/lib/utils/gcsBucketName.d.ts

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

package/lib/utils/gcsBucketName.js

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

package/lib/utils/packageManifest.d.ts

@@ -4,6 +4,8 @@ import { Exercise } from "./configBuilder";
 export declare const PACKAGE_MANIFEST_FILENAME = "package-manifest.json";
 export declare const PACKAGE_MANIFEST_REL_PATH = ".learn/package-manifest.json";
 export declare const SCHEMA_VERSION = 1;
+export declare const DESCRIPTION_PROMPT_VERSION = 1;
+export declare const DESCRIPTION_TARGET_WORD_COUNT = 25;
 export type LessonType = "READ" | "CODE" | "QUIZ";
 export type PackageManifestLesson = {
     id: string;
@@ -52,6 +54,18 @@ export declare function buildPackageManifestFromSources(input: PackageManifestBu
 export declare function parseReadmeContent(content: string): ReadmeFrontmatter;
 export declare function comparePackageManifests(existing: PackageManifest | null, next: PackageManifest): "created" | "updated" | "skipped";
 export declare function serializePackageManifest(manifest: PackageManifest): string;
+/** The manifest as it travels inside a publication event. */
+export type PackageManifestEventView = Omit<PackageManifest, "generatedAt">;
+/**
+ * Project a manifest into the shape sent to breathecode.
+ *
+ * Today this is nearly the identity — only `generatedAt`, an internal detail of
+ * the projection, is dropped. It exists as an explicit pick so that fields
+ * added to the manifest later (hashes, generation flags) do not silently become
+ * part of an external contract: joining the event payload has to be a decision
+ * visible in a diff.
+ */
+export declare function serializePackageManifestForEvent(manifest: PackageManifest): PackageManifestEventView;
 export declare function generateAndPersistPackageManifest(bucket: Bucket, courseSlug: string, options: {
     publishedAt: string | null;
     localDir?: string;

package/lib/utils/packageManifest.js

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

package/lib/utils/publishEvents.d.ts

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

package/lib/utils/publishEvents.js

@@ -0,0 +1,111 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PACKAGE_MANIFEST_UPDATED_EVENT = exports.PACKAGE_PUBLISHED_EVENT = void 0;
+exports.buildPackagePublishedEvent = buildPackagePublishedEvent;
+exports.buildPackageManifestUpdatedEvent = buildPackageManifestUpdatedEvent;
+exports.sendPublishEvent = sendPublishEvent;
+exports.fetchPackageInfo = fetchPackageInfo;
+const axios_1 = require("axios");
+const api_1 = require("./api");
+const packageManifest_1 = require("./packageManifest");
+/**
+ * Publication events sent to breathecode.
+ *
+ * They are emitted from here, and not from Rigobot, because learnpack-cli is
+ * the only party that witnesses the facts: Rigobot's part ends when the zip is
+ * deployed, before the breathecode asset sync, and it never sees the end of the
+ * asynchronous description stage.
+ *
+ * Transport is the existing telemetry endpoint. The discriminator is a
+ * top-level `event` key, which is what breathecode's webhook log already looks
+ * for; a body without it keeps being processed as plain telemetry.
+ *
+ * `package_slug` and `package_id` are duplicated at the top level on purpose:
+ * `LearnPack.add_webhook_to_log` fills the indexed columns from there, so
+ * without them the events would land as rows nobody can filter in the webhook
+ * viewer.
+ */
+exports.PACKAGE_PUBLISHED_EVENT = "package_published";
+exports.PACKAGE_MANIFEST_UPDATED_EVENT = "package_manifest_updated";
+function packageIdOf(packageInfo) {
+    const id = packageInfo === null || packageInfo === void 0 ? void 0 : packageInfo.id;
+    return typeof id === "number" ? id : undefined;
+}
+function buildPackagePublishedEvent(context, descriptions) {
+    const payload = {
+        publish_id: context.publishId,
+        package: context.packageInfo,
+        manifest: context.manifest ?
+            (0, packageManifest_1.serializePackageManifestForEvent)(context.manifest) :
+            null,
+        descriptions,
+    };
+    return {
+        event: exports.PACKAGE_PUBLISHED_EVENT,
+        package_slug: context.courseSlug,
+        package_id: packageIdOf(context.packageInfo),
+        payload: payload,
+    };
+}
+function buildPackageManifestUpdatedEvent(context, status, stats) {
+    const payload = {
+        publish_id: context.publishId,
+        status,
+        package: context.packageInfo,
+        manifest: context.manifest ?
+            (0, packageManifest_1.serializePackageManifestForEvent)(context.manifest) :
+            null,
+    };
+    if (stats) {
+        payload.stats = stats;
+    }
+    return {
+        event: exports.PACKAGE_MANIFEST_UPDATED_EVENT,
+        package_slug: context.courseSlug,
+        package_id: packageIdOf(context.packageInfo),
+        payload: payload,
+    };
+}
+/**
+ * Fire and forget: a publication must never fail because breathecode is down,
+ * so every error is swallowed and logged. Returns whether it was delivered, for
+ * the journal, not for control flow.
+ */
+async function sendPublishEvent(envelope, breathecodeToken, timeoutMs = 10000) {
+    if (!breathecodeToken) {
+        console.warn(`[publish-events] Skipping "${envelope.event}": no breathecode token`);
+        return false;
+    }
+    try {
+        await axios_1.default.post(api_1.BREATHECODE_EVENTS_URL, envelope, {
+            timeout: timeoutMs,
+            headers: {
+                "Content-Type": "application/json",
+                Authorization: "Token " + breathecodeToken.trim(),
+            },
+        });
+        return true;
+    }
+    catch (error) {
+        console.error(`[publish-events] Could not deliver "${envelope.event}" for "${envelope.package_slug}":`, error.message);
+        return false;
+    }
+}
+/**
+ * Package information for the event payload, straight from Rigobot's own
+ * serializer so the shape stays owned by the system that owns the model.
+ * Returns null on failure: an event with less context still beats no event.
+ */
+async function fetchPackageInfo(courseSlug, rigobotToken) {
+    try {
+        const response = await axios_1.default.get(`${api_1.RIGOBOT_HOST}/v1/learnpack/package/${courseSlug}/`, {
+            timeout: 10000,
+            headers: { Authorization: "Token " + rigobotToken.trim() },
+        });
+        return response.data;
+    }
+    catch (error) {
+        console.error(`[publish-events] Could not read package "${courseSlug}" from Rigobot:`, error.message);
+        return null;
+    }
+}

package/lib/utils/publishJournal.d.ts

@@ -0,0 +1,119 @@
+import { Bucket } from "@google-cloud/storage";
+/**
+ * Publish journal — per-stage state of a publication.
+ *
+ * Publishing is a distributed transaction across three systems (S3 via Rigobot,
+ * breathecode assets, and our own buckets) plus an asynchronous description
+ * stage. Some of its outcomes are NOT derivable from content afterwards: in
+ * particular "was the manifest-updated event already emitted?" leaves no trace
+ * in S3 or GCS. The journal records what happened per stage so the sweep can
+ * resume an interrupted publication and honour the event contract (a publish
+ * that announced `descriptions: "queued"` must always be followed by exactly
+ * one `package_manifest_updated`).
+ *
+ * Design notes:
+ *
+ * - **Best effort, never a lock.** Every write swallows its errors: if the
+ *   journal cannot be written the publication still proceeds. Losing the
+ *   journal degrades us to the previous behaviour (no recovery, no diagnosis),
+ *   which is acceptable; blocking a publication because a bookkeeping write
+ *   failed is not.
+ * - **Flat key space.** Journals live in `publish-journal/{slug}__{id}.json`,
+ *   a sibling prefix of `courses/`, so the sweep can list every unfinished
+ *   publication with one prefix query and the concurrency guard can list a
+ *   single course with another, without maintaining an index.
+ * - **Explicit cleanup.** A journal is deleted once every stage succeeded, and
+ *   kept when any stage failed (visibility + retry). GCS lifecycle rules would
+ *   be the natural alternative, but the service account only holds
+ *   object-level permissions (`storage.buckets.*` is denied), so the cleanup
+ *   has to happen in code.
+ */
+export declare const JOURNAL_PREFIX = "publish-journal/";
+/**
+ * Stages of a publication, in execution order.
+ *
+ * Only stages the orchestrator can observe on its own: writing the asset id
+ * back into Rigobot happens inside the asset sync call, so it is covered by
+ * `assetsSync` rather than being a stage that could never be marked.
+ */
+export declare const STAGE_NAMES: readonly ["deploy", "assetsSync", "publishedEvent", "descriptions", "gcsMirror", "manifestEvent"];
+export type StageName = typeof STAGE_NAMES[number];
+export type StageStatus = "pending" | "running" | "done" | "failed";
+export type Stage = {
+    status: StageStatus;
+    at?: string;
+    error?: string;
+    meta?: unknown;
+};
+export type PublishJournal = {
+    publishId: string;
+    courseSlug: string;
+    startedAt: string;
+    updatedAt: string;
+    /** Times the sweep has picked this journal up, to bound retries. */
+    attempts: number;
+    /** Set once retries are exhausted: kept for a human, ignored by the sweep. */
+    abandoned?: boolean;
+    stages: Record<StageName, Stage>;
+};
+export type JournalRef = {
+    courseSlug: string;
+    publishId: string;
+    key: string;
+};
+/**
+ * Minimal storage surface the journal needs, so callers can pass the real
+ * bucket adapter or an in-memory double. Object-level operations only.
+ */
+export interface JournalStorage {
+    save(key: string, contents: string): Promise<void>;
+    read(key: string): Promise<string | null>;
+    remove(key: string): Promise<void>;
+    list(prefix: string): Promise<string[]>;
+}
+export declare function journalKey(courseSlug: string, publishId: string): string;
+export declare function coursePrefix(courseSlug: string): string;
+/** Inverse of `journalKey`; returns null for keys that don't match the shape. */
+export declare function parseJournalKey(key: string): JournalRef | null;
+/**
+ * Start a journal for a new publication. The generated `publishId` correlates
+ * the two publish events and is returned even if persisting failed.
+ */
+export declare function createJournal(storage: JournalStorage, courseSlug: string, publishId?: string): Promise<PublishJournal>;
+/** Update one stage and persist. Mutates and returns the same journal object. */
+export declare function markStage(storage: JournalStorage, journal: PublishJournal, stage: StageName, status: StageStatus, extra?: {
+    error?: string;
+    meta?: unknown;
+}): Promise<PublishJournal>;
+/** Read a journal. Returns null when missing or unreadable. */
+export declare function readJournal(storage: JournalStorage, courseSlug: string, publishId: string): Promise<PublishJournal | null>;
+export declare function readJournalByKey(storage: JournalStorage, key: string): Promise<PublishJournal | null>;
+/**
+ * Every journal still stored, i.e. every publication that did not finish
+ * cleanly. Returns an empty list on error (the sweep falls back to its deep
+ * scan rather than crashing).
+ */
+export declare function listJournalRefs(storage: JournalStorage): Promise<JournalRef[]>;
+/** Journals of a single course; backs the concurrent-publish guard. */
+export declare function listJournalRefsForCourse(storage: JournalStorage, courseSlug: string): Promise<JournalRef[]>;
+export declare function isStageTerminal(stage: Stage): boolean;
+export declare function hasFailedStage(journal: PublishJournal): boolean;
+/** True when no stage is left to run (all done, or done/failed mix). */
+export declare function isJournalSettled(journal: PublishJournal): boolean;
+/** Stages the sweep still has work to do on. */
+export declare function pendingStages(journal: PublishJournal): StageName[];
+/** A journal untouched for longer than `maxAgeMs` is presumed interrupted. */
+export declare function isJournalStale(journal: PublishJournal, maxAgeMs: number, now?: number): boolean;
+export declare function incrementAttempts(storage: JournalStorage, journal: PublishJournal): Promise<PublishJournal>;
+/**
+ * Give up on a journal after too many attempts. It is kept, not deleted: a
+ * publication that never completed is exactly what someone needs to see.
+ */
+export declare function abandonJournal(storage: JournalStorage, journal: PublishJournal): Promise<PublishJournal>;
+/**
+ * Close a journal: delete it when every stage succeeded, keep it otherwise so
+ * the sweep can retry and a human can inspect it. Never throws.
+ */
+export declare function finalizeJournal(storage: JournalStorage, journal: PublishJournal): Promise<"deleted" | "kept">;
+/** GCS-backed adapter. Object-level operations only, by design. */
+export declare function createGcsJournalStorage(bucket: Bucket): JournalStorage;