@learnpack/learnpack 5.0.352 → 5.0.354

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;

package/lib/utils/publishJournal.js

@@ -0,0 +1,275 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.STAGE_NAMES = exports.JOURNAL_PREFIX = void 0;
+exports.journalKey = journalKey;
+exports.coursePrefix = coursePrefix;
+exports.parseJournalKey = parseJournalKey;
+exports.createJournal = createJournal;
+exports.markStage = markStage;
+exports.readJournal = readJournal;
+exports.readJournalByKey = readJournalByKey;
+exports.listJournalRefs = listJournalRefs;
+exports.listJournalRefsForCourse = listJournalRefsForCourse;
+exports.isStageTerminal = isStageTerminal;
+exports.hasFailedStage = hasFailedStage;
+exports.isJournalSettled = isJournalSettled;
+exports.pendingStages = pendingStages;
+exports.isJournalStale = isJournalStale;
+exports.incrementAttempts = incrementAttempts;
+exports.abandonJournal = abandonJournal;
+exports.finalizeJournal = finalizeJournal;
+exports.createGcsJournalStorage = createGcsJournalStorage;
+const uuid_1 = require("uuid");
+/**
+ * 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.
+ */
+exports.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.
+ */
+exports.STAGE_NAMES = [
+    "deploy",
+    "assetsSync",
+    "publishedEvent",
+    "descriptions",
+    "gcsMirror",
+    "manifestEvent",
+];
+function journalKey(courseSlug, publishId) {
+    return `${exports.JOURNAL_PREFIX}${courseSlug}__${publishId}.json`;
+}
+function coursePrefix(courseSlug) {
+    return `${exports.JOURNAL_PREFIX}${courseSlug}__`;
+}
+/** Inverse of `journalKey`; returns null for keys that don't match the shape. */
+function parseJournalKey(key) {
+    if (!key.startsWith(exports.JOURNAL_PREFIX) || !key.endsWith(".json")) {
+        return null;
+    }
+    const name = key.slice(exports.JOURNAL_PREFIX.length, -".json".length);
+    const separator = name.indexOf("__");
+    if (separator <= 0) {
+        return null;
+    }
+    const courseSlug = name.slice(0, separator);
+    const publishId = name.slice(separator + 2);
+    if (!courseSlug || !publishId) {
+        return null;
+    }
+    return { courseSlug, publishId, key };
+}
+function emptyStages() {
+    const stages = {};
+    for (const name of exports.STAGE_NAMES) {
+        stages[name] = { status: "pending" };
+    }
+    return stages;
+}
+/** Persist the journal. Never throws: bookkeeping must not break a publish. */
+async function persist(storage, journal) {
+    try {
+        await storage.save(journalKey(journal.courseSlug, journal.publishId), JSON.stringify(journal, null, 2));
+    }
+    catch (error) {
+        console.warn(`[publish-journal] Could not persist journal for "${journal.courseSlug}":`, error.message);
+    }
+}
+/**
+ * Start a journal for a new publication. The generated `publishId` correlates
+ * the two publish events and is returned even if persisting failed.
+ */
+async function createJournal(storage, courseSlug, publishId = (0, uuid_1.v4)()) {
+    const now = new Date().toISOString();
+    const journal = {
+        publishId,
+        courseSlug,
+        startedAt: now,
+        updatedAt: now,
+        attempts: 0,
+        stages: emptyStages(),
+    };
+    await persist(storage, journal);
+    return journal;
+}
+/** Update one stage and persist. Mutates and returns the same journal object. */
+async function markStage(storage, journal, stage, status, extra = {}) {
+    const next = { status, at: new Date().toISOString() };
+    if (extra.error !== undefined) {
+        next.error = extra.error;
+    }
+    if (extra.meta !== undefined) {
+        next.meta = extra.meta;
+    }
+    journal.stages[stage] = next;
+    journal.updatedAt = next.at;
+    await persist(storage, journal);
+    return journal;
+}
+/** Read a journal. Returns null when missing or unreadable. */
+async function readJournal(storage, courseSlug, publishId) {
+    return readJournalByKey(storage, journalKey(courseSlug, publishId));
+}
+async function readJournalByKey(storage, key) {
+    try {
+        const raw = await storage.read(key);
+        if (!raw) {
+            return null;
+        }
+        const parsed = JSON.parse(raw);
+        if (!parsed || !parsed.publishId || !parsed.stages) {
+            return null;
+        }
+        // Tolerate journals written before a stage was added to STAGE_NAMES.
+        for (const name of exports.STAGE_NAMES) {
+            if (!parsed.stages[name]) {
+                parsed.stages[name] = { status: "pending" };
+            }
+        }
+        return parsed;
+    }
+    catch (error) {
+        console.warn(`[publish-journal] Could not read journal "${key}":`, error.message);
+        return 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).
+ */
+async function listJournalRefs(storage) {
+    return listRefsByPrefix(storage, exports.JOURNAL_PREFIX);
+}
+/** Journals of a single course; backs the concurrent-publish guard. */
+async function listJournalRefsForCourse(storage, courseSlug) {
+    return listRefsByPrefix(storage, coursePrefix(courseSlug));
+}
+async function listRefsByPrefix(storage, prefix) {
+    try {
+        const keys = await storage.list(prefix);
+        const refs = [];
+        for (const key of keys) {
+            const ref = parseJournalKey(key);
+            if (ref) {
+                refs.push(ref);
+            }
+        }
+        return refs;
+    }
+    catch (error) {
+        console.warn(`[publish-journal] Could not list journals "${prefix}":`, error.message);
+        return [];
+    }
+}
+function isStageTerminal(stage) {
+    return stage.status === "done" || stage.status === "failed";
+}
+function hasFailedStage(journal) {
+    return exports.STAGE_NAMES.some(name => journal.stages[name].status === "failed");
+}
+/** True when no stage is left to run (all done, or done/failed mix). */
+function isJournalSettled(journal) {
+    return exports.STAGE_NAMES.every(name => isStageTerminal(journal.stages[name]));
+}
+/** Stages the sweep still has work to do on. */
+function pendingStages(journal) {
+    return exports.STAGE_NAMES.filter(name => !isStageTerminal(journal.stages[name]));
+}
+/** A journal untouched for longer than `maxAgeMs` is presumed interrupted. */
+function isJournalStale(journal, maxAgeMs, now = Date.now()) {
+    const updatedAt = Date.parse(journal.updatedAt);
+    if (Number.isNaN(updatedAt)) {
+        return true;
+    }
+    return now - updatedAt > maxAgeMs;
+}
+async function incrementAttempts(storage, journal) {
+    journal.attempts += 1;
+    journal.updatedAt = new Date().toISOString();
+    await persist(storage, journal);
+    return journal;
+}
+/**
+ * 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.
+ */
+async function abandonJournal(storage, journal) {
+    journal.abandoned = true;
+    journal.updatedAt = new Date().toISOString();
+    await persist(storage, journal);
+    return journal;
+}
+/**
+ * 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.
+ */
+async function finalizeJournal(storage, journal) {
+    if (!isJournalSettled(journal) || hasFailedStage(journal)) {
+        await persist(storage, journal);
+        return "kept";
+    }
+    try {
+        await storage.remove(journalKey(journal.courseSlug, journal.publishId));
+        return "deleted";
+    }
+    catch (error) {
+        console.warn(`[publish-journal] Could not delete journal for "${journal.courseSlug}":`, error.message);
+        return "kept";
+    }
+}
+/** GCS-backed adapter. Object-level operations only, by design. */
+function createGcsJournalStorage(bucket) {
+    return {
+        async save(key, contents) {
+            await bucket.file(key).save(Buffer.from(contents, "utf8"), {
+                contentType: "application/json",
+            });
+        },
+        async read(key) {
+            try {
+                const [buf] = await bucket.file(key).download();
+                return buf.toString();
+            }
+            catch (_a) {
+                return null;
+            }
+        },
+        async remove(key) {
+            await bucket.file(key).delete();
+        },
+        async list(prefix) {
+            const [files] = await bucket.getFiles({ prefix });
+            return files.map(file => file.name);
+        },
+    };
+}

package/lib/utils/repair/legacyPackageRepair.d.ts

@@ -0,0 +1,131 @@
+import { Syllabus } from "../../models/creator";
+import { Exercise } from "../configBuilder";
+import { LessonType } from "../packageManifest";
+import { RepairStorage, RepairTarget } from "./repairStorage";
+/**
+ * Reconstruct the manifest inputs missing from legacy packages.
+ *
+ * Some packages predate the creator — a few were uploaded straight from a GitHub
+ * repository — and never got a `.learn/initialSyllabus.json`, a
+ * `.learn/sidebar.json`, or a usable `config.json`. The manifest tolerates the
+ * first two and comes out degraded: every lesson typed `READ`, and descriptions
+ * pinned to `null` forever, because `descriptionsS3Backfill` builds its work
+ * list from the syllabus keys and never even sees a course without one.
+ *
+ * This module writes those files back, derived from what the package *does*
+ * have: its exercise folders and their READMEs. It never invents content — a
+ * title comes from the README's own `# H1`, never from an LLM.
+ *
+ * It runs once per bucket (see `repairStorage.ts` for why the draft is repaired
+ * from the draft rather than copied from the snapshot). Ordering afterwards:
+ *
+ *   1. this script, on both targets                       (structure)
+ *   2. `descriptionsS3Backfill --reproject-manifest --mirror-draft`
+ *   3. `backfill:package-manifest`, unless step 2 projected it
+ *
+ * Safety: with one documented exception (a `config.json` whose `exercises` array
+ * is empty, which is merged rather than replaced) it only ever writes keys that
+ * do not exist. It never touches a file the real pipeline produced.
+ */
+export type RepairFile = "config" | "syllabus" | "sidebar";
+export declare const ALL_REPAIR_FILES: RepairFile[];
+export type FileOutcome = "created" | "merged" | "present" | "not-requested" | "impossible";
+export type FileResult = {
+    outcome: FileOutcome;
+    key?: string;
+    reason?: string;
+};
+export type RepairStats = {
+    exercises: number;
+    languages: string[];
+    primaryLanguage: string;
+    lessonTypes: Record<LessonType, number>;
+    titlesFromReadme: number;
+    titlesFromFolderName: number;
+};
+export type RepairResult = {
+    slug: string;
+    target: RepairTarget;
+    /**
+     * `absent` is not a failure: half the legacy packages published in S3 have no
+     * draft in GCS at all, so a run over both buckets is expected to find nothing
+     * to repair on one side. Only a package that *is* in the bucket but yields no
+     * exercises counts as `failed`.
+     */
+    status: "repaired" | "unchanged" | "absent" | "failed";
+    durationMs: number;
+    files: Record<RepairFile, FileResult>;
+    stats?: RepairStats;
+    error?: string;
+};
+export type RepairOptions = {
+    dryRun: boolean;
+    files: RepairFile[];
+};
+/** README body + parsed title, by exercise slug and language. */
+export type ReadmeIndex = Record<string, Record<string, {
+    title: string | null;
+    body: string;
+}>>;
+/**
+ * Exercises from the bucket listing alone, mirroring `configBuilder.buildConfig`
+ * key for key: same README language rule, same natural ordering, same
+ * `graded: false` default.
+ */
+export declare function buildExercisesFromKeys(exercisesPrefix: string, keys: string[]): Exercise[];
+/**
+ * Language the course is really written in.
+ *
+ * Same rule as `workList.inferCourseBaseLanguage`: a declared language is
+ * trusted only when some exercise actually has a README in it, otherwise the
+ * most frequent translation wins. Defaulting to "en" would label a Spanish
+ * course English and anchor every later description to a translation.
+ *
+ * A bilingual course ties on count — most of the legacy ones are — so the tie is
+ * broken on the file names rather than arbitrarily: `getReadmeExtension` gives
+ * the *original* README no language suffix and suffixes every translation, so
+ * the language mapped to a bare `README.md` is the one the course was written
+ * in. This matters beyond the title: the descriptions backfill generates from
+ * `courseInfo.language` and would otherwise work from a translation.
+ */
+export declare function inferPrimaryLanguage(exercises: Exercise[], declared?: string): string;
+/**
+ * Lesson type, inferred — the one field of a synthesized syllabus that is a
+ * guess rather than a reading. Callers should treat it as such.
+ */
+export declare function inferLessonType(input: {
+    graded: boolean;
+    files: Array<{
+        name: string;
+    }>;
+    readmeBody: string;
+}): LessonType;
+export type BuildSyllabusInput = {
+    slug: string;
+    learnJson: Record<string, unknown> | null;
+    exercises: Exercise[];
+    readmes: ReadmeIndex;
+    primaryLanguage: string;
+};
+export type BuildSyllabusResult = {
+    syllabus: Syllabus;
+    stats: Omit<RepairStats, "exercises" | "languages" | "primaryLanguage">;
+};
+/**
+ * A syllabus equivalent to what the creator would have written, derived from the
+ * exercise folders and their READMEs.
+ *
+ * `uid` is set to the exercise folder slug on purpose. `findSyllabusLesson`
+ * matches on `slugify(id + "-" + title)` *or* `uid`, and only the second is
+ * guaranteed to hold once a title comes from an H1 the folder name never had —
+ * it is also what lets the S3 and GCS repairs, run independently, still line up
+ * for the descriptions mirror.
+ */
+export declare function buildSyllabusFromSources(input: BuildSyllabusInput): BuildSyllabusResult;
+/** `sidebar[exerciseSlug][lang] = title`, from the same READMEs. */
+export declare function buildSidebarFromReadmes(exercises: Exercise[], readmes: ReadmeIndex): Record<string, Record<string, string>>;
+/**
+ * Repair one package in one bucket. Returns what it did (or would do, under
+ * `dryRun`) without throwing: a batch reports failures per slug.
+ */
+export declare function repairPackage(storage: RepairStorage, slug: string, options: RepairOptions): Promise<RepairResult>;