@learnpack/learnpack 5.0.353 → 5.0.354

package/lib/utils/repair/repairStorage.js

@@ -0,0 +1,89 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.gcsLayout = exports.s3Layout = exports.ALL_REPAIR_TARGETS = void 0;
+exports.createS3RepairStorage = createS3RepairStorage;
+exports.createGcsRepairStorage = createGcsRepairStorage;
+const client_s3_1 = require("@aws-sdk/client-s3");
+const packageManifestBackfill_1 = require("../s3/packageManifestBackfill");
+exports.ALL_REPAIR_TARGETS = ["s3", "gcs"];
+exports.s3Layout = {
+    learnJsonKey: slug => `${slug}/learn.json`,
+    configKeys: slug => [`${slug}/config.json`, `${slug}/.learn/config.json`],
+    syllabusKey: slug => `${slug}/.learn/initialSyllabus.json`,
+    // 25 of the published packages keep their sidebar at the root. It has to be
+    // resolved before writing: `fetchPackageSources` prefers the `.learn/` copy,
+    // so a synthesized one would shadow the published titles.
+    sidebarKeys: slug => [
+        `${slug}/.learn/sidebar.json`,
+        `${slug}/sidebar.json`,
+    ],
+    exercisesPrefix: slug => `${slug}/exercises/`,
+    exercisesFromConfig: true,
+};
+exports.gcsLayout = {
+    learnJsonKey: slug => `courses/${slug}/learn.json`,
+    configKeys: slug => [
+        `courses/${slug}/.learn/config.json`,
+        `courses/${slug}/config.json`,
+    ],
+    syllabusKey: slug => `courses/${slug}/.learn/initialSyllabus.json`,
+    sidebarKeys: slug => [`courses/${slug}/.learn/sidebar.json`],
+    exercisesPrefix: slug => `courses/${slug}/exercises/`,
+    exercisesFromConfig: false,
+};
+function createS3RepairStorage(s3, bucket) {
+    return {
+        target: "s3",
+        layout: exports.s3Layout,
+        readJson: key => (0, packageManifestBackfill_1.fetchJsonObject)(s3, bucket, key),
+        readText: key => (0, packageManifestBackfill_1.fetchTextObject)(s3, bucket, key),
+        listKeys: prefix => (0, packageManifestBackfill_1.listObjectKeys)(s3, bucket, prefix),
+        async writeJson(key, value) {
+            await (0, packageManifestBackfill_1.withRetry)(() => s3.send(new client_s3_1.PutObjectCommand({
+                Bucket: bucket,
+                Key: key,
+                Body: JSON.stringify(value, null, 2),
+                ContentType: "application/json",
+            })));
+        },
+    };
+}
+function createGcsRepairStorage(bucket) {
+    const download = async (key) => {
+        try {
+            const [buf] = await bucket.file(key).download();
+            return buf.toString();
+        }
+        catch (_a) {
+            return null;
+        }
+    };
+    return {
+        target: "gcs",
+        layout: exports.gcsLayout,
+        async readJson(key) {
+            const content = await download(key);
+            if (content === null) {
+                return null;
+            }
+            try {
+                return JSON.parse(content);
+            }
+            catch (_a) {
+                return null;
+            }
+        },
+        readText: download,
+        async listKeys(prefix) {
+            const [files] = await bucket.getFiles({ prefix });
+            return files.map(file => file.name);
+        },
+        async writeJson(key, value) {
+            await bucket
+                .file(key)
+                .save(Buffer.from(JSON.stringify(value, null, 2), "utf8"), {
+                contentType: "application/json",
+            });
+        },
+    };
+}

package/lib/utils/s3/packageManifestBackfill.js

@@ -16,6 +16,7 @@ exports.getBatchExitCode = getBatchExitCode;
 const tslib_1 = require("tslib");
 const client_cloudfront_1 = require("@aws-sdk/client-cloudfront");
 const client_s3_1 = require("@aws-sdk/client-s3");
+const awsCredentials_1 = require("../awsCredentials");
 const packageManifest_1 = require("../packageManifest");
 const README_FILENAME_PATTERN = /^readme(?:\.[a-z]{2})?\.md$/i;
 const INDEX_HTML_PATTERN = /^[^/]+\/index\.html$/;
@@ -389,18 +390,12 @@ async function runBatch(options, clients) {
     const s3 = (clients === null || clients === void 0 ? void 0 : clients.s3) ||
         new client_s3_1.S3Client({
             region: options.region,
-            credentials: {
-                accessKeyId: process.env.AWS_ACCESS_KEY_ID || "",
-                secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY || "",
-            },
+            credentials: (0, awsCredentials_1.requireAwsCredentials)(),
         });
     const cf = (clients === null || clients === void 0 ? void 0 : clients.cf) ||
         new client_cloudfront_1.CloudFrontClient({
             region: "us-east-1",
-            credentials: {
-                accessKeyId: process.env.AWS_ACCESS_KEY_ID || "",
-                secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY || "",
-            },
+            credentials: (0, awsCredentials_1.requireAwsCredentials)(),
         });
     let slugs = options.slug ?
         [options.slug] :

package/lib/utils/s3/packageSourcesAudit.d.ts

@@ -0,0 +1,75 @@
+import { AwsClient } from "./packageManifestBackfill";
+/**
+ * Inventory of the files a published package needs for its
+ * `package-manifest.json` to be generated at full fidelity.
+ *
+ * This reads **key names only** — one paginated `ListObjectsV2` over the bucket,
+ * zero `GetObject`. Cheap enough to run over the whole catalogue on demand, and
+ * safe at any time: it never writes.
+ *
+ * What it answers: which packages would *fail* the manifest backfill (no
+ * `config.json`, no exercises), and which ones only produce a *degraded*
+ * manifest (no `initialSyllabus.json` → every lesson typed `READ`, ids derived
+ * from the folder name, and descriptions permanently `null`, because the
+ * descriptions pipeline builds its work list from the syllabus keys and cannot
+ * see a course that has none).
+ *
+ * Companion of `legacyPackageRepair.ts`, which writes what this reports missing.
+ */
+export type PackageSourcesAuditEntry = {
+    slug: string;
+    /** A published package is a prefix holding an `index.html` at its root. */
+    hasIndexHtml: boolean;
+    /** Required: without it the manifest backfill reports `failed`. */
+    hasConfigJson: boolean;
+    configJsonKey: string | null;
+    /**
+     * Optional *as a key*: `config.json` may carry the same metadata under
+     * `config`. Only a `GetObject` could tell, so `false` here means "resolves
+     * through the fallback, or not at all" — not "broken".
+     */
+    hasLearnJson: boolean;
+    hasSyllabus: boolean;
+    hasSidebar: boolean;
+    sidebarKey: string | null;
+    hasManifest: boolean;
+    /** Folders directly under `exercises/` holding at least one object. */
+    exerciseFolders: number;
+    /** `README.md` / `README.xx.md` files found in those folders. */
+    readmeCount: number;
+    /** Missing inputs, named as in the docs, for quick reporting. */
+    missing: string[];
+    /** True when the manifest backfill cannot produce a manifest at all. */
+    blocking: boolean;
+};
+export type PackageSourcesAuditSummary = {
+    missingConfigJson: number;
+    missingLearnJson: number;
+    missingSyllabus: number;
+    missingSidebar: number;
+    missingManifest: number;
+    noExerciseFolders: number;
+    blocking: number;
+};
+export type PackageSourcesAuditReport = {
+    generatedAt: string;
+    bucket: string;
+    scannedKeys: number;
+    totalPackages: number;
+    summary: PackageSourcesAuditSummary;
+    packages: PackageSourcesAuditEntry[];
+};
+export type AuditOptions = {
+    /** Restrict the scan to a single package (uses a prefixed listing). */
+    slug?: string;
+    /** Keep prefixes with no `index.html` (drafts, leftovers). Default false. */
+    includeUnpublished?: boolean;
+};
+export declare function summarize(packages: PackageSourcesAuditEntry[]): PackageSourcesAuditSummary;
+/**
+ * One paginated pass over the bucket, folding each page into the accumulator.
+ *
+ * Deliberately not built on `listObjectKeys`: that one materializes every key in
+ * the catalogue before the caller sees the first one.
+ */
+export declare function auditPackageSources(s3: AwsClient, bucket: string, options?: AuditOptions): Promise<PackageSourcesAuditReport>;

package/lib/utils/s3/packageSourcesAudit.js

@@ -0,0 +1,184 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.summarize = summarize;
+exports.auditPackageSources = auditPackageSources;
+const client_s3_1 = require("@aws-sdk/client-s3");
+const packageManifestBackfill_1 = require("./packageManifestBackfill");
+const README_FILENAME_PATTERN = /^readme(?:\.[a-z]{2})?\.md$/i;
+const ROOT_FILES = new Set([
+    "index.html",
+    "learn.json",
+    "config.json",
+    ".learn/config.json",
+    ".learn/initialSyllabus.json",
+    ".learn/sidebar.json",
+    "sidebar.json",
+    ".learn/package-manifest.json",
+]);
+function emptyAccumulator(slug) {
+    return {
+        slug,
+        hasIndexHtml: false,
+        configJsonKey: null,
+        hasLearnJson: false,
+        hasSyllabus: false,
+        sidebarKey: null,
+        hasManifest: false,
+        exerciseFolders: new Set(),
+        readmeCount: 0,
+    };
+}
+/** Fold one object key into the accumulator map. */
+function classifyKey(entries, key) {
+    const separatorIndex = key.indexOf("/");
+    if (separatorIndex <= 0) {
+        // Object at the bucket root: not part of any package.
+        return;
+    }
+    const slug = key.slice(0, separatorIndex);
+    const rest = key.slice(separatorIndex + 1);
+    if (!rest) {
+        return;
+    }
+    const exerciseParts = rest.startsWith("exercises/") ? rest.split("/") : [];
+    // `exercises/<slug>/<file>`: shorter paths are the folder marker itself.
+    const exerciseSlug = exerciseParts.length >= 3 && exerciseParts[1] ? exerciseParts[1] : null;
+    if (!ROOT_FILES.has(rest) && !exerciseSlug) {
+        return;
+    }
+    let entry = entries.get(slug);
+    if (!entry) {
+        entry = emptyAccumulator(slug);
+        entries.set(slug, entry);
+    }
+    if (exerciseSlug) {
+        entry.exerciseFolders.add(exerciseSlug);
+        const filename = exerciseParts[exerciseParts.length - 1];
+        if (exerciseParts.length === 3 && README_FILENAME_PATTERN.test(filename)) {
+            entry.readmeCount += 1;
+        }
+        return;
+    }
+    switch (rest) {
+        case "index.html":
+            entry.hasIndexHtml = true;
+            break;
+        case "learn.json":
+            entry.hasLearnJson = true;
+            break;
+        // The root copy wins over `.learn/config.json`, matching the order
+        // `fetchPackageSources` resolves them in. Same for the sidebar, inverted.
+        case "config.json":
+            entry.configJsonKey = key;
+            break;
+        case ".learn/config.json":
+            entry.configJsonKey = entry.configJsonKey || key;
+            break;
+        case ".learn/sidebar.json":
+            entry.sidebarKey = key;
+            break;
+        case "sidebar.json":
+            entry.sidebarKey = entry.sidebarKey || key;
+            break;
+        case ".learn/initialSyllabus.json":
+            entry.hasSyllabus = true;
+            break;
+        case ".learn/package-manifest.json":
+            entry.hasManifest = true;
+            break;
+        default:
+            break;
+    }
+}
+function finalizeEntry(entry) {
+    const missing = [];
+    if (!entry.configJsonKey) {
+        missing.push("config.json");
+    }
+    if (!entry.hasLearnJson) {
+        missing.push("learn.json");
+    }
+    if (!entry.hasSyllabus) {
+        missing.push("initialSyllabus.json");
+    }
+    if (!entry.sidebarKey) {
+        missing.push("sidebar.json");
+    }
+    if (entry.exerciseFolders.size === 0) {
+        missing.push("exercises/");
+    }
+    if (!entry.hasManifest) {
+        missing.push("package-manifest.json");
+    }
+    return {
+        slug: entry.slug,
+        hasIndexHtml: entry.hasIndexHtml,
+        hasConfigJson: Boolean(entry.configJsonKey),
+        configJsonKey: entry.configJsonKey,
+        hasLearnJson: entry.hasLearnJson,
+        hasSyllabus: entry.hasSyllabus,
+        hasSidebar: Boolean(entry.sidebarKey),
+        sidebarKey: entry.sidebarKey,
+        hasManifest: entry.hasManifest,
+        exerciseFolders: entry.exerciseFolders.size,
+        readmeCount: entry.readmeCount,
+        missing,
+        // A missing `learn.json` is not blocking on its own: `config.config` can
+        // stand in for it, and only a download would tell.
+        blocking: !entry.configJsonKey || entry.exerciseFolders.size === 0,
+    };
+}
+function count(packages, predicate) {
+    return packages.filter(entry => predicate(entry)).length;
+}
+function summarize(packages) {
+    return {
+        missingConfigJson: count(packages, entry => !entry.hasConfigJson),
+        missingLearnJson: count(packages, entry => !entry.hasLearnJson),
+        missingSyllabus: count(packages, entry => !entry.hasSyllabus),
+        missingSidebar: count(packages, entry => !entry.hasSidebar),
+        missingManifest: count(packages, entry => !entry.hasManifest),
+        noExerciseFolders: count(packages, entry => entry.exerciseFolders === 0),
+        blocking: count(packages, entry => entry.blocking),
+    };
+}
+/**
+ * One paginated pass over the bucket, folding each page into the accumulator.
+ *
+ * Deliberately not built on `listObjectKeys`: that one materializes every key in
+ * the catalogue before the caller sees the first one.
+ */
+async function auditPackageSources(s3, bucket, options = {}) {
+    const entries = new Map();
+    const prefix = options.slug ? `${options.slug}/` : undefined;
+    let continuationToken;
+    let scannedKeys = 0;
+    do {
+        // eslint-disable-next-line no-await-in-loop -- S3 pagination is sequential
+        const response = (await (0, packageManifestBackfill_1.withRetry)(() => s3.send(new client_s3_1.ListObjectsV2Command({
+            Bucket: bucket,
+            Prefix: prefix,
+            ContinuationToken: continuationToken,
+        }))));
+        for (const item of response.Contents || []) {
+            if (!item.Key) {
+                continue;
+            }
+            scannedKeys += 1;
+            classifyKey(entries, item.Key);
+        }
+        continuationToken = response.NextContinuationToken;
+    } while (continuationToken);
+    const packages = [...entries.values()]
+        .filter(entry => options.includeUnpublished || entry.hasIndexHtml)
+        .map(entry => finalizeEntry(entry))
+        .sort((a, b) => a.slug.localeCompare(b.slug));
+    return {
+        generatedAt: new Date().toISOString(),
+        bucket,
+        scannedKeys,
+        totalPackages: packages.length,
+        summary: summarize(packages),
+        packages,
+    };
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@learnpack/learnpack",
   "description": "Seamlessly build, sell and/or take interactive & auto-graded tutorials, start learning now or build a new tutorial to your audience.",
-  "version": "5.0.353",
+  "version": "5.0.354",
   "author": "Alejandro Sanchez @alesanchezr",
   "contributors": [
     {
@@ -163,7 +163,9 @@
     ]
   },
   "scripts": {
+    "audit:package-sources": "ts-node --project ./tsconfig.json ./scripts/audit-package-sources.ts",
     "backfill:package-manifest": "ts-node --project ./tsconfig.json ./scripts/backfill-package-manifest-s3.ts",
+    "repair:legacy-packages": "ts-node --project ./tsconfig.json ./scripts/repair-legacy-packages.ts",
     "copy-assets": "npx cpy src/creatorDist/**/* lib/creatorDist --parents --verbose && npx cpy src/utils/templates/**/* lib/utils/templates --parents --verbose && npx cpy src/lua/**/* lib/lua --parents --verbose",
     "tsc": "tsc -b",
     "postpack": "rm -f oclif.manifest.json && eslint . --ext .ts --config .eslintrc",

package/src/scripts/README.md

@@ -0,0 +1,244 @@
+# Descriptions scripts (`src/scripts/`)
+
+Ops scripts for the **step descriptions** of published courses. They are dev/ops
+entry points, not oclif commands: they never appear under `learnpack <something>`
+and are run with `node` against the compiled output.
+
+| Script                    | What it does                                                            | Calls the LLM |
+| ------------------------- | ----------------------------------------------------------------------- | ------------- |
+| `descriptionsS3Backfill`  | Generates descriptions for **published** courses (S3)                   | Yes           |
+| `descriptionsGcsBackfill` | Copies existing descriptions from S3 into the **draft** (GCS)           | No            |
+| `descriptionsSweep`       | Finishes publications that stalled mid-flight; runs on Heroku Scheduler | Yes           |
+
+All three delegate the per-course work to the same service,
+[`generateCourseDescriptions`](../utils/descriptions/generateCourseDescriptions.ts),
+which is also what the post-publish stage uses. They differ only in **which**
+courses they run it on and **what else** they do around it.
+
+## Build and run
+
+```bash
+npm run tsc
+node lib/scripts/<script>.js [flags]
+```
+
+They run against `lib/`, not `src/`, so recompile after editing. There is no
+`--help`: the flags are documented here and in each script's header.
+
+## Environment
+
+Copy from [`.env.example`](../../.env.example) into `learnpack-cli/.env`. These
+scripts read `process.env` directly — they do **not** load the `.env` themselves,
+so export it (`set -a; . ./.env; set +a`) or pass the variables inline.
+
+| Variable                                   | Needed by                                                                       |
+| ------------------------------------------ | ------------------------------------------------------------------------------- |
+| `RIGOBOT_SYSTEM_TOKEN`                     | S3 backfill, sweep (generation)                                                 |
+| `BREATHECODE_SYSTEM_TOKEN`                 | `--emit-events`, sweep (pending events)                                         |
+| `AWS_ACCESS_KEY_ID` / `_SECRET_ACCESS_KEY` | anything reading the published bucket                                           |
+| `AWS_REGION`                               | optional, default `us-east-1`                                                   |
+| `S3_PACKAGES_BUCKET`                       | optional in the backfills (default `learnpack-paquetes`), required by the sweep |
+| `CLOUDFRONT_DISTRIBUTION_ID`               | optional; without it manifests are re-projected but not invalidated             |
+| `GCP_CREDENTIALS_JSON`                     | GCS backfill, sweep, `--mirror-draft`                                           |
+| `GCP_BUCKET_NAME`                          | same; no default on purpose                                                     |
+
+Descriptions are always generated with the Rigobot **service** account, never
+with a user token: they are platform enrichment, not something a creator is
+billed for.
+
+---
+
+## Mode 1 — targeted run (a few slugs, on demand)
+
+The everyday case: a course was published before descriptions existed, or one
+needs remediation. Three flags make the S3 backfill reproduce per course
+everything a publication does, in one process:
+
+```bash
+node lib/scripts/descriptionsS3Backfill.js --slug my-course \
+  --reproject-manifest --mirror-draft --emit-events --concurrency 2
+```
+
+| Flag                   | Without it                                                                              |
+| ---------------------- | --------------------------------------------------------------------------------------- |
+| `--reproject-manifest` | `package-manifest.json` keeps the old descriptions until a later pass                   |
+| `--mirror-draft`       | the draft has no fingerprints, so the **next publication regenerates the whole course** |
+| `--emit-events`        | breathecode is never told the manifest changed                                          |
+
+All three are off by default, so the catalogue-wide run below is unaffected.
+
+Run it once per slug. Do a `--dry-run` first if you want to see the scope —
+it reports what it would generate and mirror without writing anything.
+
+**During high-traffic hours**, lower `--concurrency` (default 5 completions in
+flight per course). A single completion takes ~15s.
+
+Notes:
+
+- `--emit-events` **requires** `--reproject-manifest`. The event reports a
+  manifest update, so emitting it without projecting would state something
+  untrue. It is required rather than implied on purpose: writing to S3 and the
+  CDN as a side effect of another flag is the kind of surprise a backfill should
+  not have.
+- `--emit-events` is rejected together with `--dry-run`: there is no dry run of
+  an event breathecode already received.
+- `--mirror-draft` is independent of the other two — it touches the draft, not
+  the manifest.
+- Prefer `--slug` over `--limit 4` when you care about _which_ courses are
+  touched: `--limit` counts **processed** courses (already-settled ones are
+  skipped without counting) and walks the catalogue by recency.
+
+### What each course does, in order
+
+1. Generate the missing descriptions and write them into the published
+   `initialSyllabus.json` (S3).
+2. `--reproject-manifest`: rebuild `package-manifest.json` from that syllabus
+   (the same `processPackage` the manifest backfill runs) and invalidate its
+   CloudFront path.
+3. `--mirror-draft`: copy the descriptions back into the GCS draft, guarded by
+   the README content hash — anything the teacher edited since publishing is
+   counted as `missed` and waits for the next publication.
+4. `--emit-events`: send `package_manifest_updated` to breathecode.
+
+A failure in step 3 does not change the event status: the published package and
+its manifest are already correct, only the draft lags behind. A failure in step 2
+**does** — see below.
+
+---
+
+## Mode 2 — catalogue backfill (fases 0a / 0b)
+
+The one-off sweep over the ~400 published courses and ~800 drafts. Here the
+defaults are the right ones: manifests are cheaper to project in a single later
+pass than course by course, and the draft is seeded by copy rather than by
+re-generating.
+
+```bash
+# Fase 0a — descriptions for the published catalogue, 50 courses per run.
+# Re-run until it stops reporting processed courses.
+node lib/scripts/descriptionsS3Backfill.js --limit 50
+
+# Then project every manifest in one pass (cheaper than per course).
+npm run backfill:package-manifest
+
+# Fase 0b — seed the drafts by copying from S3. Never calls the LLM.
+node lib/scripts/descriptionsGcsBackfill.js --limit 200
+```
+
+Order matters: 0b reads the **published** syllabus, so 0a must have written it
+first. Whatever 0b cannot reuse (drafts edited since their last publication) is
+left for the next publication of that course, or for a single-slug 0a run.
+
+No events are emitted in this mode. If breathecode needs to be told about the
+catalogue, that is a separate decision — adding `--emit-events` to a 400-course
+run would deliver 400 events.
+
+---
+
+## Flag reference
+
+### `descriptionsS3Backfill`
+
+| Flag                   | Default              | Description                                                       |
+| ---------------------- | -------------------- | ----------------------------------------------------------------- |
+| `--slug <slug>`        | —                    | single course (remediation / on-demand)                           |
+| `--limit <n>`          | 50                   | courses **processed** per run, ordered by syllabus recency        |
+| `--s3-bucket <name>`   | `learnpack-paquetes` | published bucket                                                  |
+| `--gcs-bucket <name>`  | `GCP_BUCKET_NAME`    | draft bucket, for `--mirror-draft`                                |
+| `--region <region>`    | `us-east-1`          | AWS region                                                        |
+| `--concurrency <n>`    | 5                    | completions in flight per course                                  |
+| `--target-words <n>`   | 25                   | words per description                                             |
+| `--dry-run`            | off                  | preview; no writes, no completions                                |
+| `--force`              | off                  | regenerate courses already settled at the current prompt version  |
+| `--no-reconcile`       | off                  | skip the additive syllabus reconciliation                         |
+| `--reproject-manifest` | off                  | rebuild + invalidate `package-manifest.json` per course           |
+| `--mirror-draft`       | off                  | copy the descriptions into the GCS draft                          |
+| `--emit-events`        | off                  | send `package_manifest_updated` (requires `--reproject-manifest`) |
+
+### `descriptionsGcsBackfill`
+
+| Flag                  | Default              | Description                      |
+| --------------------- | -------------------- | -------------------------------- |
+| `--slug <slug>`       | —                    | single course                    |
+| `--limit <n>`         | 50                   | courses per run                  |
+| `--s3-bucket <name>`  | `learnpack-paquetes` | source (published) bucket        |
+| `--gcs-bucket <name>` | `GCP_BUCKET_NAME`    | target (draft) bucket            |
+| `--region <region>`   | `us-east-1`          | AWS region                       |
+| `--dry-run`           | off                  | preview without writing          |
+| `--no-reconcile`      | off                  | skip the syllabus reconciliation |
+
+### `descriptionsSweep`
+
+No flags — it is a scheduled job, configured by env:
+
+```bash
+node lib/scripts/descriptionsSweep.js
+```
+
+Two sources of work:
+
+1. **Publish journals** (`publish-journal/` in GCS), the primary one. Every
+   publication that stalled is resumed: missing descriptions generated, draft
+   mirrored, and the owed `package_manifest_updated` emitted. Journals are
+   dropped once complete and abandoned after a few attempts.
+2. **A deep scan** of published courses (`DESCRIPTIONS_SWEEP_FULL=1`), for
+   packages that never got a journal at all. Expensive — it reads every course —
+   and off by default. It re-projects manifests but does **not** emit events.
+
+Tuning: `DESCRIPTIONS_SWEEP_LIMIT` (courses per deep scan, default 25),
+`DESCRIPTION_STALE_AFTER_MS` (how long a publication may look stalled before it
+is resumed, default 15 min).
+
+---
+
+## The `package_manifest_updated` event
+
+Emitted by `--emit-events`, and by the sweep for the publications it finishes.
+Built in [`publishEvents.ts`](../utils/publishEvents.ts), sent to the breathecode
+telemetry endpoint with `BREATHECODE_SYSTEM_TOKEN`.
+
+Breathecode processes it **independently of `package_published`**, so a backfill
+event with no preceding publication is fine.
+
+**`publish_id` in a backfill** is `backfill-{runId}-{slug}`:
+
+- the `backfill-` prefix makes the origin readable in the webhook log and
+  discriminable in code (`isBackfillPublishId`); real publish ids are bare
+  uuids, so the two spaces cannot collide;
+- `{slug}` keeps it unique per event;
+- `{runId}` is one uuid per **invocation**, shared by every course it touches, so
+  "every event from the run I fired at 15:40" is a single substring query. It is
+  printed at start and in the closing summary.
+
+Note that running four separate `--slug` commands produces four run ids. Use
+`--limit` if you want one id for the batch — at the cost of not choosing the
+slugs.
+
+**Status is tied to the real outcome**, not to the script finishing:
+
+| Outcome                                  | `status`  |
+| ---------------------------------------- | --------- |
+| Descriptions written, manifest projected | `success` |
+| Generation failed outright               | `failed`  |
+| Manifest projection failed               | `failed`  |
+| Course unchanged (`skipped`)             | no event  |
+| Course threw                             | no event  |
+
+A failed manifest projection is not a failed run — the syllabus, which is the
+source of truth, is already saved — but this event reports the manifest, so it
+cannot claim success over one that was never rewritten. That is what
+`GenerateCourseDescriptionsResult.manifestProjected` exists for.
+
+The last row is deliberate: unlike a publication, a backfill never _announced_ an
+event, so it owes none. The course is simply re-run.
+
+---
+
+## Related
+
+- [`../utils/descriptions/`](../utils/descriptions/) — the shared service, the
+  mirror, the post-publish stage and the resume logic
+- [`../../scripts/README.md`](../../scripts/README.md) — the package-manifest S3
+  backfill (`npm run backfill:package-manifest`)
+- [`../utils/publishJournal.ts`](../utils/publishJournal.ts) — why the sweep can
+  know an event is owed