@learnpack/learnpack 5.0.351 → 5.0.353

package/src/utils/packageManifest.ts

@@ -13,6 +13,14 @@ const frontMatter = require("front-matter")
 export const PACKAGE_MANIFEST_FILENAME = "package-manifest.json"
 export const PACKAGE_MANIFEST_REL_PATH = ".learn/package-manifest.json"
 export const 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.
+export const DESCRIPTION_PROMPT_VERSION = 1
+
+// Target length, in words, of a generated step description.
+export const DESCRIPTION_TARGET_WORD_COUNT = 25
 
 export type LessonType = "READ" | "CODE" | "QUIZ";
 
@@ -22,6 +30,7 @@ export type PackageManifestLesson = {
   position: number;
   type: LessonType;
   title: Record<string, string>;
+  description: Record<string, string | null>;
   video: Record<string, string | null>;
 };
 
@@ -165,6 +174,24 @@ function resolveLessonTitle(
   return titles
 }
 
+function resolveLessonDescriptions(
+  exercise: Exercise,
+  syllabusLesson: Lesson | undefined
+): Record<string, string | null> {
+  const description: Record<string, string | null> = {}
+
+  // 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)) {
+    description[lang] =
+      syllabusLesson?.translations?.[lang]?.description ?? null
+  }
+
+  return description
+}
+
 function resolveLessonVideos(
   exercise: Exercise,
   readmeFrontmatters: Record<string, Record<string, ReadmeFrontmatter>>
@@ -226,6 +253,7 @@ export function buildPackageManifestFromSources(
         courseLang,
         readmeFrontmatters[exercise.slug] ?? {}
       ),
+      description: resolveLessonDescriptions(exercise, syllabusLesson),
       video: resolveLessonVideos(exercise, readmeFrontmatters),
     }
   })
@@ -263,6 +291,77 @@ async function downloadJsonFile<T>(
   }
 }
 
+export function parseReadmeContent(content: string): ReadmeFrontmatter {
+  const parsed = frontMatter(content)
+  const attributes = parsed.attributes || {}
+  const h1 = extractReadmeH1(parsed.body || "")
+  const title = h1 ? normalizeReadmeTitle(h1) : null
+  return {
+    ...(attributes.tutorial ? { tutorial: attributes.tutorial } : {}),
+    ...(attributes.intro ? { intro: attributes.intro } : {}),
+    ...(title ? { title } : {}),
+  }
+}
+
+export function comparePackageManifests(
+  existing: PackageManifest | null,
+  next: PackageManifest
+): "created" | "updated" | "skipped" {
+  if (existing === null) {
+    return "created"
+  }
+
+  const { generatedAt: _existingGeneratedAt, ...existingRest } = existing
+  const { generatedAt: _nextGeneratedAt, ...nextRest } = next
+
+  if (JSON.stringify(existingRest) === JSON.stringify(nextRest)) {
+    return "skipped"
+  }
+
+  return "updated"
+}
+
+export function serializePackageManifest(manifest: PackageManifest): string {
+  return JSON.stringify(manifest, null, 2)
+}
+
+/** 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 function serializePackageManifestForEvent(
+  manifest: PackageManifest
+): PackageManifestEventView {
+  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: Bucket,
   exerciseSlug: string,
@@ -275,18 +374,10 @@ async function readReadmeFrontmatter(
 }> {
   try {
     const [buf] = await bucket.file(readmePath).download()
-    const parsed = frontMatter(buf.toString())
-    const attributes = parsed.attributes || {}
-    const h1 = extractReadmeH1(parsed.body || "")
-    const title = h1 ? normalizeReadmeTitle(h1) : null
     return {
       exerciseSlug,
       lang,
-      frontmatter: {
-        tutorial: attributes.tutorial,
-        intro: attributes.intro,
-        ...(title ? { title } : {}),
-      },
+      frontmatter: parseReadmeContent(buf.toString()),
     }
   } catch (error) {
     console.warn(
@@ -328,7 +419,7 @@ function writeManifestJson(
   manifest: PackageManifest,
   localDir?: string
 ): string {
-  const json = JSON.stringify(manifest, null, 2)
+  const json = serializePackageManifest(manifest)
 
   if (localDir) {
     const learnDir = path.join(localDir, ".learn")

package/src/utils/publishEvents.ts

@@ -0,0 +1,181 @@
+import axios from "axios"
+import { BREATHECODE_EVENTS_URL, RIGOBOT_HOST } from "./api"
+import {
+  PackageManifest,
+  PackageManifestEventView,
+  serializePackageManifestForEvent,
+} 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 const PACKAGE_PUBLISHED_EVENT = "package_published"
+export 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;
+};
+
+function packageIdOf(
+  packageInfo: Record<string, unknown> | null
+): number | undefined {
+  const id = packageInfo?.id
+  return typeof id === "number" ? id : undefined
+}
+
+export function buildPackagePublishedEvent(
+  context: PublishEventContext,
+  descriptions: DescriptionsOutcome
+): PublishEventEnvelope {
+  const payload: PackagePublishedPayload = {
+    publish_id: context.publishId,
+    package: context.packageInfo,
+    manifest: context.manifest ?
+      serializePackageManifestForEvent(context.manifest) :
+      null,
+    descriptions,
+  }
+
+  return {
+    event: PACKAGE_PUBLISHED_EVENT,
+    package_slug: context.courseSlug,
+    package_id: packageIdOf(context.packageInfo),
+    payload: payload as unknown as Record<string, unknown>,
+  }
+}
+
+export function buildPackageManifestUpdatedEvent(
+  context: PublishEventContext,
+  status: "success" | "failed",
+  stats?: PackageManifestUpdatedPayload["stats"]
+): PublishEventEnvelope {
+  const payload: PackageManifestUpdatedPayload = {
+    publish_id: context.publishId,
+    status,
+    package: context.packageInfo,
+    manifest: context.manifest ?
+      serializePackageManifestForEvent(context.manifest) :
+      null,
+  }
+
+  if (stats) {
+    payload.stats = stats
+  }
+
+  return {
+    event: PACKAGE_MANIFEST_UPDATED_EVENT,
+    package_slug: context.courseSlug,
+    package_id: packageIdOf(context.packageInfo),
+    payload: payload as unknown as Record<string, unknown>,
+  }
+}
+
+/**
+ * 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 async function sendPublishEvent(
+  envelope: PublishEventEnvelope,
+  breathecodeToken: string,
+  timeoutMs = 10_000
+): Promise<boolean> {
+  if (!breathecodeToken) {
+    console.warn(
+      `[publish-events] Skipping "${envelope.event}": no breathecode token`
+    )
+    return false
+  }
+
+  try {
+    await axios.post(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 as 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.
+ */
+export async function fetchPackageInfo(
+  courseSlug: string,
+  rigobotToken: string
+): Promise<Record<string, unknown> | null> {
+  try {
+    const response = await axios.get(
+      `${RIGOBOT_HOST}/v1/learnpack/package/${courseSlug}/`,
+      {
+        timeout: 10_000,
+        headers: { Authorization: "Token " + rigobotToken.trim() },
+      }
+    )
+    return response.data as Record<string, unknown>
+  } catch (error) {
+    console.error(
+      `[publish-events] Could not read package "${courseSlug}" from Rigobot:`,
+      (error as Error).message
+    )
+    return null
+  }
+}