@learnpack/learnpack 5.0.355 → 5.0.357

package/lib/services/ingest/core/ingestCoursePackage.d.ts

@@ -0,0 +1,52 @@
+import { CourseStorage } from "../ports/courseStorage";
+import { PackageRegistry } from "../ports/packageRegistry";
+import { PackageFiles } from "./validatePackage";
+import { SkippedLesson } from "./types";
+export type IngestInput = {
+    files: PackageFiles;
+    /** Slug the caller asked for; derived from the title when absent. */
+    requestedSlug?: string;
+    /** Whether the caller accepted overwriting a course they already own. */
+    overwrite: boolean;
+};
+export type IngestDeps = {
+    storage: CourseStorage;
+    /** Registry already scoped to the calling user's token. */
+    registry: PackageRegistry;
+    /** Organization every ingested package must end up under. */
+    organization: string;
+    now?: number;
+};
+export type IngestReport = {
+    slug: string;
+    packageId: number;
+    organization: string;
+    lessons: number;
+    /** Planned lessons the package held no content for. */
+    skipped: SkippedLesson[];
+    written: number;
+    deleted: number;
+    /**
+     * True when the slug was already registered but its bucket was empty, so this
+     * run completed an earlier attempt instead of overwriting anything.
+     */
+    recoveredEmptyPackage: boolean;
+};
+/**
+ * Ingests a finished course package: registers it and writes it to the bucket.
+ *
+ * The order is validate → resolve slug → register → write → prune, and it is
+ * not arbitrary. Validation and slug resolution are free and catch most bad
+ * requests; registration is the first thing that can conflict, and doing it
+ * before any write means a rejected course leaves nothing behind.
+ *
+ * Failures throw `IngestError` rather than being collected into the report. A
+ * partial ingest has no useful middle state to report — unlike publishing,
+ * nothing here runs detached after the response, so there is nothing for a
+ * later sweep to resume. Re-running is the recovery path, and the empty-package
+ * case above is what keeps that from being blocked.
+ * @param input - The extracted package and the caller's choices.
+ * @param deps - Storage, registry and expected organization.
+ * @returns What was written.
+ */
+export declare function ingestCoursePackage(input: IngestInput, deps: IngestDeps): Promise<IngestReport>;

package/lib/services/ingest/core/ingestCoursePackage.js

@@ -0,0 +1,217 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ingestCoursePackage = ingestCoursePackage;
+const console_1 = require("../../../utils/console");
+const packageManifestBackfill_1 = require("../../../utils/s3/packageManifestBackfill");
+const errors_1 = require("../errors");
+const buildIngestConfig_1 = require("./buildIngestConfig");
+const buildInitialSyllabus_1 = require("./buildInitialSyllabus");
+const buildSidebar_1 = require("./buildSidebar");
+const coursePaths_1 = require("./coursePaths");
+const normalizeLearnJson_1 = require("./normalizeLearnJson");
+const pairLessons_1 = require("./pairLessons");
+const planWrites_1 = require("./planWrites");
+const resolveSlug_1 = require("./resolveSlug");
+const validatePackage_1 = require("./validatePackage");
+/** Enough parallelism to hide the round trip without opening a socket per file. */
+const WRITE_CONCURRENCY = 10;
+const parseJson = (raw, path) => {
+    try {
+        return JSON.parse(raw);
+    }
+    catch (error) {
+        throw new errors_1.IngestError("INVALID_PACKAGE", `${path} is not valid JSON: ${error.message}`, error);
+    }
+};
+/**
+ * Reads the GitHub connection a previous config may hold.
+ *
+ * A user can link a course to a repository from the creator, and that link
+ * lives in `config.github`. Re-ingesting rewrites `config.json` wholesale, so
+ * without carrying this across, an overwrite would quietly disconnect a
+ * repository nobody asked to disconnect. `GET /config` guards the same field
+ * the same way.
+ * @param storage - Course storage.
+ * @param slug - Course slug.
+ * @returns The stored github block, or undefined.
+ */
+async function readGithubConnection(storage, slug) {
+    var _a;
+    const raw = await storage.read((0, coursePaths_1.configPath)(slug));
+    if (!raw) {
+        return undefined;
+    }
+    try {
+        const existing = JSON.parse(raw);
+        return (_a = existing === null || existing === void 0 ? void 0 : existing.config) === null || _a === void 0 ? void 0 : _a.github;
+    }
+    catch (_b) {
+        // A config we cannot parse has nothing to preserve; the fresh one wins.
+        return undefined;
+    }
+}
+/**
+ * Turns the configured organization into the id everything else speaks.
+ *
+ * Configuration names an organization the way a person would, but a package
+ * reports its organization as a numeric id: the field is a plain ForeignKey on
+ * a ModelSerializer, so it serializes to the primary key, and no endpoint ever
+ * returns a slug. Comparing the two directly is how a correctly configured
+ * ingest ends up refused with "belongs to organization 105, not learnpack-labs".
+ *
+ * Accepts an id as-is, and otherwise matches case-insensitively against the
+ * names of the organizations the caller belongs to. A miss lists them, since
+ * nothing else in the flow would ever show the reader an id to use.
+ * @param configured - Value of INGEST_ORGANIZATION.
+ * @param registry - Used to list the caller's organizations.
+ * @returns The organization id.
+ * @throws IngestError `ORGANIZATION_MISMATCH` listing the available options.
+ */
+async function resolveOrganizationId(configured, registry) {
+    const asId = Number(configured);
+    if (Number.isInteger(asId) && asId > 0) {
+        return asId;
+    }
+    const organizations = await registry.listOrganizations();
+    const wanted = configured.trim().toLowerCase();
+    const match = organizations.find(org => (org.name || "").trim().toLowerCase() === wanted);
+    if (match) {
+        return match.id;
+    }
+    const available = organizations
+        .map(org => `${org.id} (${org.name})`)
+        .join(", ");
+    throw new errors_1.IngestError("ORGANIZATION_MISMATCH", available ?
+        `INGEST_ORGANIZATION is "${configured}", which matches none of your organizations: ${available}. Use one of those ids or its exact name.` :
+        `INGEST_ORGANIZATION is "${configured}", but this token belongs to no organization`);
+}
+/**
+ * Settles the package registration for a slug the caller may already own.
+ *
+ * Registering before writing is deliberate: it is the cheap check that catches
+ * a slug collision or a wrong organization while the bucket is still untouched.
+ * @param slug - Resolved slug.
+ * @param learnJson - Normalized learn.json, stored as the package config.
+ * @param deps - Registry and expected organization.
+ * @param overwrite - Whether the caller accepted overwriting their own course.
+ * @param storage - Used to tell an abandoned registration from a real course.
+ * @returns The package and whether this run is completing an earlier attempt.
+ */
+async function registerPackage(slug, learnJson, deps, overwrite, storage) {
+    const available = await deps.registry.isSlugAvailable(slug);
+    if (available) {
+        return {
+            pkg: await deps.registry.createPackage(slug, learnJson),
+            recovered: false,
+        };
+    }
+    const existing = await deps.registry.getPackageBySlug(slug);
+    if (!existing) {
+        // Taken, and the registry will not show it to us: it belongs to another
+        // user. No suggestion is offered here — the caller cannot fix this by
+        // retrying, only by choosing a different slug.
+        throw new errors_1.IngestError("SLUG_OWNED_BY_OTHER", `The slug "${slug}" belongs to another user`);
+    }
+    if (!overwrite) {
+        const contents = await storage.list((0, coursePaths_1.coursePrefix)(slug));
+        // A registered slug with an empty bucket is the fingerprint of a run that
+        // registered and then failed before writing. Refusing it would strand the
+        // user behind a 409 for a course that, as far as they can tell, does not
+        // exist.
+        if (contents.length === 0) {
+            console_1.default.info(`[ingest] "${slug}" was registered but never written; completing that attempt`);
+            return { pkg: existing, recovered: true };
+        }
+        const suggestions = await (0, resolveSlug_1.suggestSlugs)(slug, deps.registry);
+        throw new errors_1.IngestError("SLUG_TAKEN", `You already have a course at "${slug}". Re-run with overwrite to replace it, or use one of: ${suggestions.join(", ")}`);
+    }
+    return { pkg: existing, recovered: false };
+}
+/**
+ * Ingests a finished course package: registers it and writes it to the bucket.
+ *
+ * The order is validate → resolve slug → register → write → prune, and it is
+ * not arbitrary. Validation and slug resolution are free and catch most bad
+ * requests; registration is the first thing that can conflict, and doing it
+ * before any write means a rejected course leaves nothing behind.
+ *
+ * Failures throw `IngestError` rather than being collected into the report. A
+ * partial ingest has no useful middle state to report — unlike publishing,
+ * nothing here runs detached after the response, so there is nothing for a
+ * later sweep to resume. Re-running is the recovery path, and the empty-package
+ * case above is what keeps that from being blocked.
+ * @param input - The extracted package and the caller's choices.
+ * @param deps - Storage, registry and expected organization.
+ * @returns What was written.
+ */
+async function ingestCoursePackage(input, deps) {
+    (0, validatePackage_1.validatePackage)(input.files);
+    const rawLearnJson = parseJson(input.files[validatePackage_1.LEARN_JSON_PATH], validatePackage_1.LEARN_JSON_PATH);
+    const plan = parseJson(input.files[validatePackage_1.LESSON_PLAN_PATH], validatePackage_1.LESSON_PLAN_PATH);
+    const slug = (0, resolveSlug_1.resolveSlug)({
+        requestedSlug: input.requestedSlug,
+        courseTitle: plan.course_title,
+    });
+    const learnJson = (0, normalizeLearnJson_1.normalizeLearnJson)({ learnJson: rawLearnJson, slug });
+    const { pkg, recovered } = await registerPackage(slug, learnJson, deps, input.overwrite, deps.storage);
+    const organizationId = await resolveOrganizationId(deps.organization, deps.registry);
+    if (pkg.organization === null) {
+        await deps.registry.assignOrganization(pkg.id, organizationId);
+    }
+    else if (pkg.organization !== organizationId) {
+        // There is no way to detach an organization through the API, so landing in
+        // the wrong one is only fixable by hand. Better to stop before writing.
+        throw new errors_1.IngestError("ORGANIZATION_MISMATCH", `"${slug}" belongs to organization ${pkg.organization}, not ${organizationId} (${deps.organization})`);
+    }
+    const { slugs, languagesBySlug } = (0, validatePackage_1.readExercises)(input.files);
+    const { lessons, skipped } = (0, pairLessons_1.pairLessons)(plan, slugs, languagesBySlug);
+    const language = (plan.language || "en").trim().toLowerCase() || "en";
+    const syllabus = (0, buildInitialSyllabus_1.buildInitialSyllabus)({
+        slug,
+        language,
+        lessons,
+        learnJson,
+        now: deps.now,
+    });
+    const sidebar = (0, buildSidebar_1.buildSidebar)(lessons);
+    const github = input.overwrite ?
+        await readGithubConnection(deps.storage, slug) :
+        undefined;
+    const projected = (0, buildIngestConfig_1.buildIngestConfig)({ lessons, learnJson });
+    const config = github ? Object.assign(Object.assign({}, projected), { config: Object.assign(Object.assign({}, projected.config), { github }) }) :
+        projected;
+    const writes = (0, planWrites_1.planWrites)({
+        slug,
+        files: input.files,
+        lessons,
+        learnJson,
+        syllabus,
+        sidebar,
+        config,
+    });
+    let deleted = 0;
+    if (input.overwrite) {
+        const existing = await deps.storage.list((0, coursePaths_1.coursePrefix)(slug));
+        const stale = (0, planWrites_1.planDeletions)(existing, new Set(writes.keys()), slug);
+        await deps.storage.deleteMany(stale);
+        deleted = stale.length;
+    }
+    // Written in parallel, with a cap. A course is around fifty small objects —
+    // one README per lesson plus the generation artifacts — and one round trip at
+    // a time turned a few seconds of work into most of a minute, long enough for
+    // the uploading client to give up while the server was still writing.
+    await (0, packageManifestBackfill_1.mapWithConcurrency)([...writes.entries()], WRITE_CONCURRENCY, ([path, contents]) => deps.storage.write(path, contents));
+    if (skipped.length > 0) {
+        console_1.default.warning(`[ingest] "${slug}": ${skipped.length} planned lesson(s) had no content and were left out`);
+    }
+    return {
+        slug,
+        packageId: pkg.id,
+        organization: deps.organization,
+        lessons: lessons.length,
+        skipped,
+        written: writes.size,
+        deleted,
+        recoveredEmptyPackage: recovered,
+    };
+}

package/lib/services/ingest/core/normalizeLearnJson.d.ts

@@ -0,0 +1,25 @@
+export type NormalizeLearnJsonInput = {
+    /** The `learn.json` shipped inside the package. */
+    learnJson: Record<string, unknown>;
+    /** The slug the ingest resolved, which wins over whatever the package says. */
+    slug: string;
+};
+/**
+ * Fills in the fields the generator's exporter omits.
+ *
+ * The generator writes a `learn.json` good enough to run locally, but three
+ * fields only matter once the course lives in the bucket, and each fails
+ * quietly when missing:
+ *
+ * - `telemetry.batch` — without it student telemetry is never sent.
+ * - `preview` — publish falls back to the generic LearnPack logo.
+ * - `technologies` — the organization package listing filters on it.
+ *
+ * The slug is overwritten rather than trusted: it is resolved against the
+ * registry before anything is written, and the copy inside the package predates
+ * that. Leaving them to disagree puts the bucket path and `learn.json` out of
+ * sync, which `change-slug` would then fail to reconcile.
+ * @param input - The package's learn.json and the resolved slug.
+ * @returns A learn.json ready to be written to the bucket.
+ */
+export declare function normalizeLearnJson(input: NormalizeLearnJsonInput): Record<string, unknown>;

package/lib/services/ingest/core/normalizeLearnJson.js

@@ -0,0 +1,29 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.normalizeLearnJson = normalizeLearnJson;
+const api_1 = require("../../../utils/api");
+/**
+ * Fills in the fields the generator's exporter omits.
+ *
+ * The generator writes a `learn.json` good enough to run locally, but three
+ * fields only matter once the course lives in the bucket, and each fails
+ * quietly when missing:
+ *
+ * - `telemetry.batch` — without it student telemetry is never sent.
+ * - `preview` — publish falls back to the generic LearnPack logo.
+ * - `technologies` — the organization package listing filters on it.
+ *
+ * The slug is overwritten rather than trusted: it is resolved against the
+ * registry before anything is written, and the copy inside the package predates
+ * that. Leaving them to disagree puts the bucket path and `learn.json` out of
+ * sync, which `change-slug` would then fail to reconcile.
+ * @param input - The package's learn.json and the resolved slug.
+ * @returns A learn.json ready to be written to the bucket.
+ */
+function normalizeLearnJson(input) {
+    const { learnJson, slug } = input;
+    const telemetry = learnJson.telemetry || {};
+    return Object.assign(Object.assign({}, learnJson), { slug, technologies: Array.isArray(learnJson.technologies) ?
+            learnJson.technologies :
+            [], telemetry: Object.assign(Object.assign({}, telemetry), { batch: telemetry.batch || api_1.BREATHECODE_TELEMETRY_URL }), preview: learnJson.preview || `https://${slug}.learn-pack.com/preview.png` });
+}

package/lib/services/ingest/core/pairLessons.d.ts

@@ -0,0 +1,29 @@
+import { IngestLesson, LessonPlan, SkippedLesson } from "./types";
+/**
+ * The exercise folder a lesson id owns, e.g. "01.1" for "01.1-split-a-class".
+ *
+ * Parsed by splitting rather than by a two-digit regex: the generator's own id
+ * parser accepts "1.0", so a stricter pattern here would reject a plan the
+ * generator considers valid.
+ * @param exerciseSlug - Folder name inside `exercises/`.
+ * @returns The leading id, or the whole slug when there is no hyphen.
+ */
+export declare function lessonIdFromSlug(exerciseSlug: string): string;
+export type PairLessonsResult = {
+    lessons: IngestLesson[];
+    skipped: SkippedLesson[];
+};
+/**
+ * Matches planned lessons to the exercise folders that actually hold content.
+ *
+ * A plan lists every lesson that was *planned*; module-batched generation can
+ * stop early, leaving later modules without files. Pairing against the folders
+ * present is what makes a partial course ingest as the eight lessons it has
+ * rather than the twelve it intended — and the leftovers are reported instead
+ * of dropped, so nobody discovers the gap by scrolling the IDE.
+ * @param plan - The generator's lesson plan.
+ * @param exerciseSlugs - Folder names found under `exercises/` in the package.
+ * @param languagesBySlug - Language codes with a README, per exercise slug.
+ * @returns Paired lessons in plan order, plus the entries that had no content.
+ */
+export declare function pairLessons(plan: LessonPlan, exerciseSlugs: string[], languagesBySlug: Record<string, string[]>): PairLessonsResult;

package/lib/services/ingest/core/pairLessons.js

@@ -0,0 +1,102 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.lessonIdFromSlug = lessonIdFromSlug;
+exports.pairLessons = pairLessons;
+const console_1 = require("../../../utils/console");
+const VALID_LESSON_TYPES = new Set(["READ", "CODE", "QUIZ"]);
+/**
+ * The exercise folder a lesson id owns, e.g. "01.1" for "01.1-split-a-class".
+ *
+ * Parsed by splitting rather than by a two-digit regex: the generator's own id
+ * parser accepts "1.0", so a stricter pattern here would reject a plan the
+ * generator considers valid.
+ * @param exerciseSlug - Folder name inside `exercises/`.
+ * @returns The leading id, or the whole slug when there is no hyphen.
+ */
+function lessonIdFromSlug(exerciseSlug) {
+    const [head] = exerciseSlug.split("-");
+    return head;
+}
+/**
+ * Reads the lesson type, falling back rather than failing.
+ *
+ * The generator declares this as a Pydantic Literal, so a successfully
+ * generated course cannot carry anything else — but the package is consumed
+ * long after the fact, and a course that renders every lesson as READ beats one
+ * that refuses to ingest.
+ * @param type - Raw value from the plan.
+ * @param lessonId - Used to make the warning actionable.
+ * @returns A valid lesson type.
+ */
+function coerceLessonType(type, lessonId) {
+    if (type && VALID_LESSON_TYPES.has(type)) {
+        return type;
+    }
+    if (type) {
+        console_1.default.warning(`[ingest] Lesson ${lessonId} has unknown type "${type}"; treating it as READ`);
+    }
+    return "READ";
+}
+/**
+ * The generation topic for a lesson.
+ *
+ * `lesson_focus` is absent in packages from the pre-ADR-0001 schema, and this
+ * value is not what students read — the student-facing description lives per
+ * language in `translations[lang].description`, which the descriptions backfill
+ * fills in later. The title is a fine stand-in.
+ * @param lesson - Planned lesson.
+ * @returns The focus, or the title.
+ */
+function describeLesson(lesson) {
+    const focus = (lesson.lesson_focus || "").trim();
+    return focus || lesson.title;
+}
+/**
+ * Matches planned lessons to the exercise folders that actually hold content.
+ *
+ * A plan lists every lesson that was *planned*; module-batched generation can
+ * stop early, leaving later modules without files. Pairing against the folders
+ * present is what makes a partial course ingest as the eight lessons it has
+ * rather than the twelve it intended — and the leftovers are reported instead
+ * of dropped, so nobody discovers the gap by scrolling the IDE.
+ * @param plan - The generator's lesson plan.
+ * @param exerciseSlugs - Folder names found under `exercises/` in the package.
+ * @param languagesBySlug - Language codes with a README, per exercise slug.
+ * @returns Paired lessons in plan order, plus the entries that had no content.
+ */
+function pairLessons(plan, exerciseSlugs, languagesBySlug) {
+    const slugsById = new Map();
+    for (const slug of exerciseSlugs) {
+        const id = lessonIdFromSlug(slug);
+        // First folder wins: a duplicate id means the package is malformed, and
+        // picking arbitrarily is no worse than picking the last one.
+        if (!slugsById.has(id)) {
+            slugsById.set(id, slug);
+        }
+    }
+    const lessons = [];
+    const skipped = [];
+    for (const planned of plan.lessons || []) {
+        const exerciseSlug = slugsById.get(planned.id);
+        if (!exerciseSlug) {
+            skipped.push({
+                id: planned.id,
+                title: planned.title,
+                reason: "no-content",
+            });
+            continue;
+        }
+        lessons.push({
+            id: planned.id,
+            exerciseSlug,
+            title: planned.title,
+            type: coerceLessonType(planned.type, planned.id),
+            durationMinutes: typeof planned.duration_minutes === "number" ?
+                planned.duration_minutes :
+                0,
+            description: describeLesson(planned),
+            languages: languagesBySlug[exerciseSlug] || [],
+        });
+    }
+    return { lessons, skipped };
+}

package/lib/services/ingest/core/planWrites.d.ts

@@ -0,0 +1,44 @@
+import { PackageFiles } from "./validatePackage";
+import { IngestLesson } from "./types";
+export type PlanWritesInput = {
+    slug: string;
+    files: PackageFiles;
+    lessons: IngestLesson[];
+    learnJson: Record<string, unknown>;
+    syllabus: unknown;
+    sidebar: unknown;
+    config: unknown;
+};
+/**
+ * Lays out every object the ingest will write, keyed by its bucket path.
+ *
+ * Returned rather than written so the orchestrator can compare the plan against
+ * what is already in the bucket before touching anything — which is what makes
+ * pruning stale lessons possible, and what lets a test assert the whole tree
+ * without a storage double.
+ *
+ * Content files ride through verbatim; only the four derived documents are
+ * generated. Note `.learn/config.json` from the package is *not* among them:
+ * it is a projection of the other files, and the copy the generator ships
+ * carries localhost URLs and a stale exercise list.
+ * @param input - Slug, package files and the derived documents.
+ * @returns Bucket path → contents.
+ */
+export declare function planWrites(input: PlanWritesInput): Map<string, string>;
+/**
+ * Objects the course still holds that this ingest is not going to rewrite.
+ *
+ * Scoped to the prefixes the ingest owns. Everything else under the course
+ * belongs to somebody else — preview images the user uploaded,
+ * `package-manifest.json`, the publish journal — and deleting those would
+ * destroy work the ingest never created.
+ *
+ * Pruning matters because `buildConfig` derives the exercise list from whatever
+ * files exist: a regenerated course with fewer lessons would otherwise keep
+ * listing the old folders as lessons that open empty.
+ * @param existing - Every object path currently under the course.
+ * @param planned - Paths this ingest is about to write.
+ * @param slug - Course slug, for scoping the prunable prefixes.
+ * @returns Paths safe to delete.
+ */
+export declare function planDeletions(existing: string[], planned: Set<string>, slug: string): string[];

package/lib/services/ingest/core/planWrites.js

@@ -0,0 +1,59 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.planWrites = planWrites;
+exports.planDeletions = planDeletions;
+const coursePaths_1 = require("./coursePaths");
+/** Package paths copied through untouched, keyed by their prefix. */
+const PASSTHROUGH_PREFIXES = [".learn/artifacts/", "exercises/"];
+const normalize = (path) => path.replace(/\\/g, "/");
+const stringify = (value) => JSON.stringify(value, null, 2);
+/**
+ * Lays out every object the ingest will write, keyed by its bucket path.
+ *
+ * Returned rather than written so the orchestrator can compare the plan against
+ * what is already in the bucket before touching anything — which is what makes
+ * pruning stale lessons possible, and what lets a test assert the whole tree
+ * without a storage double.
+ *
+ * Content files ride through verbatim; only the four derived documents are
+ * generated. Note `.learn/config.json` from the package is *not* among them:
+ * it is a projection of the other files, and the copy the generator ships
+ * carries localhost URLs and a stale exercise list.
+ * @param input - Slug, package files and the derived documents.
+ * @returns Bucket path → contents.
+ */
+function planWrites(input) {
+    const writes = new Map();
+    const prefix = (0, coursePaths_1.coursePrefix)(input.slug);
+    for (const [rawPath, contents] of Object.entries(input.files)) {
+        const path = normalize(rawPath);
+        if (PASSTHROUGH_PREFIXES.some(known => path.startsWith(known))) {
+            writes.set(`${prefix}${path}`, contents);
+        }
+    }
+    writes.set((0, coursePaths_1.learnJsonPath)(input.slug), stringify(input.learnJson));
+    writes.set((0, coursePaths_1.syllabusPath)(input.slug), stringify(input.syllabus));
+    writes.set((0, coursePaths_1.sidebarPath)(input.slug), stringify(input.sidebar));
+    writes.set((0, coursePaths_1.configPath)(input.slug), stringify(input.config));
+    return writes;
+}
+/**
+ * Objects the course still holds that this ingest is not going to rewrite.
+ *
+ * Scoped to the prefixes the ingest owns. Everything else under the course
+ * belongs to somebody else — preview images the user uploaded,
+ * `package-manifest.json`, the publish journal — and deleting those would
+ * destroy work the ingest never created.
+ *
+ * Pruning matters because `buildConfig` derives the exercise list from whatever
+ * files exist: a regenerated course with fewer lessons would otherwise keep
+ * listing the old folders as lessons that open empty.
+ * @param existing - Every object path currently under the course.
+ * @param planned - Paths this ingest is about to write.
+ * @param slug - Course slug, for scoping the prunable prefixes.
+ * @returns Paths safe to delete.
+ */
+function planDeletions(existing, planned, slug) {
+    const prunable = (0, coursePaths_1.prunablePrefixes)(slug);
+    return existing.filter(path => !planned.has(path) && prunable.some(prefix => path.startsWith(prefix)));
+}

package/lib/services/ingest/core/resolveSlug.d.ts

@@ -0,0 +1,53 @@
+import { PackageRegistry } from "../ports/packageRegistry";
+/**
+ * Room to spare under Rigobot's 100-character SlugField, so a suffixed
+ * suggestion still fits.
+ */
+export declare const MAX_SLUG_LENGTH = 80;
+/**
+ * The strictest of the slug rules in play, on purpose.
+ *
+ * This repo's own `slugify` keeps dots, and two things break when one survives:
+ * Rigobot stores `package_slug` in a Django SlugField whose validator rejects
+ * them (it persists anyway, since the view never calls full_clean), and the
+ * published course is served at `{slug}.learn-pack.com`, where a dot adds a
+ * subdomain level the wildcard certificate does not cover.
+ * @param raw - Candidate slug or title.
+ * @returns Lowercase, hyphen-separated, alphanumeric-only slug.
+ */
+export declare function normalizeSlug(raw: string): string;
+/**
+ * Proposes alternatives for a slug that is taken.
+ *
+ * Suggested rather than applied: the slug is the public URL and, in practice,
+ * permanent — the rename endpoint does not update Rigobot's copy. Auto-suffixing
+ * is how a `solid-principles-7` ends up shipped. This mirrors the creator's own
+ * publish dialog, which checks availability and lets the human choose.
+ * @param base - The slug that was taken.
+ * @param registry - Used to check each candidate.
+ * @returns Up to three available slugs.
+ */
+export declare function suggestSlugs(base: string, registry: PackageRegistry): Promise<string[]>;
+export type ResolveSlugInput = {
+    /** Slug the caller asked for, if any. */
+    requestedSlug?: string;
+    /** Course title, used to derive a slug when none was requested. */
+    courseTitle?: string;
+};
+/**
+ * Settles which slug the course will live under.
+ *
+ * An explicit slug is validated rather than repaired: silently reshaping what
+ * somebody typed hands them a different URL than the one they asked for. A
+ * derived slug is only a suggestion, which is why the caller is expected to
+ * show it.
+ *
+ * There is no shared default. An earlier version of the exporter fell back to
+ * "LearnPack Course" for an untitled course, which slugifies to
+ * `learnpack-course` for *every* such course — and since slugs are globally
+ * unique, the second one collides with the first.
+ * @param input - Requested slug and/or course title.
+ * @returns The slug to use.
+ * @throws IngestError `INVALID_SLUG` when nothing usable was given.
+ */
+export declare function resolveSlug(input: ResolveSlugInput): string;