@learnpack/learnpack 5.0.357 → 5.0.359

package/src/utils/assetSync.ts

@@ -0,0 +1,343 @@
+/**
+ * Creates or updates the Breathecode assets of a published package, one per
+ * language, and writes the resulting ids back to the Rigobot package.
+ *
+ * Kept free of fs, oclif and express so the whole decision table can be
+ * exercised with HTTP mocks alone; `publish` and `serve` only supply the
+ * readme of each language and the tokens.
+ */
+import api, { AssetSyncError, BcAsset } from "./api"
+import Console from "./console"
+import { buildAssetSlug } from "./creatorUtilities"
+import {
+  dedupeLangs,
+  describeAmbiguity,
+  getAvailableLangs,
+  PackageAssetsResolution,
+  resolvePackageAssets,
+  canonicalLang,
+} from "./assetResolver"
+
+export type AssetSyncInput = {
+  bcToken: string;
+  rigoToken: string;
+  packageSlug: string;
+  learnJson: any;
+  deployUrl: string;
+  academyId?: number;
+  /** Raw readme for a language ("" when there is none). Base64 encoding happens here. */
+  readReadme: (lang: string) => Promise<string>;
+  /** A resolution computed earlier (e.g. before the upload) to reuse instead of resolving again. */
+  resolution?: PackageAssetsResolution;
+};
+
+export type SyncedAsset = {
+  lang: string;
+  action: "created" | "updated";
+  asset: { id: number; slug: string };
+};
+
+export type AssetSyncResult = {
+  errors: AssetSyncError[];
+  warnings: string[];
+  synced: SyncedAsset[];
+};
+
+/**
+ * Localized value with the same fallbacks the publish flow always used.
+ * @param translations - A learn.json map such as `title` or `description`.
+ * @param lang - Preferred language key.
+ * @returns The value for `lang`, else "en"/"us", else the first one, else "".
+ */
+export const getLocalizedValue = (
+  translations: Record<string, any> | undefined,
+  lang: string
+): string => {
+  if (!translations || typeof translations !== "object") return ""
+
+  const direct = translations[lang]
+  if (typeof direct === "string" && direct.trim().length > 0) return direct
+
+  for (const fb of ["en", "us"]) {
+    const v = translations[fb]
+    if (typeof v === "string" && v.trim().length > 0) return v
+  }
+
+  const firstKey = Object.keys(translations)[0]
+  const first = firstKey ? translations[firstKey] : ""
+  return typeof first === "string" ? first : ""
+}
+
+type LangPlan =
+  | { lang: string; kind: "update"; asset: BcAsset; slug: string }
+  | { lang: string; kind: "create"; slug: string }
+  | { lang: string; kind: "skip"; detail: string };
+
+const packageError = (detail: string): AssetSyncError => ({
+  kind: "package_error",
+  error: { detail },
+})
+
+const langError = (lang: string, detail: string): AssetSyncError => ({
+  kind: "lang_error",
+  lang,
+  error: { detail },
+})
+
+const errorDetail = (error: unknown): string => {
+  const err: any = error
+  if (typeof err?.detail === "string") return err.detail
+  if (typeof err?.message === "string") return err.message
+  try {
+    return JSON.stringify(err)
+  } catch {
+    return String(err)
+  }
+}
+
+/**
+ * Synchronises every language of a package with Breathecode.
+ * @param input - Tokens, package data, deploy url and readme provider.
+ * @returns Per-language errors (the publish itself is never blocked), warnings worth logging, and what was written.
+ */
+export async function syncPackageAssets(
+  input: AssetSyncInput
+): Promise<AssetSyncResult> {
+  const warnings: string[] = []
+  const errors: AssetSyncError[] = []
+  const synced: SyncedAsset[] = []
+
+  const user = await api.validateToken(input.bcToken)
+  if (!user || typeof user.id !== "number") {
+    return {
+      errors: [packageError("Invalid Breathecode token; assets not synced.")],
+      warnings,
+      synced,
+    }
+  }
+
+  const resolution =
+    input.resolution ??
+    (await resolvePackageAssets({
+      bcToken: input.bcToken,
+      rigoToken: input.rigoToken,
+      packageSlug: input.packageSlug,
+      learnJson: input.learnJson,
+    }))
+  warnings.push(...resolution.warnings)
+
+  if (resolution.packageState === "unknown") {
+    return {
+      errors: [
+        packageError(
+          `${
+            resolution.packageError ?? "Existing assets could not be checked"
+          }; nothing was created or updated to avoid duplicates.`
+        ),
+      ],
+      warnings,
+      synced,
+    }
+  }
+
+  const learnpackId = resolution.learnpackId
+  if (learnpackId === null) {
+    return {
+      errors: [
+        packageError(
+          "Could not resolve Learnpack package id; assets not synced to Breathecode."
+        ),
+      ],
+      warnings,
+      synced,
+    }
+  }
+
+  // Decide every language before touching anything, so all_translations can
+  // name the full set up front (the PUT replaces the relation, it does not add).
+  const langs = dedupeLangs(getAvailableLangs(input.learnJson))
+  const plans: LangPlan[] = []
+  for (const lang of langs) {
+    const title = getLocalizedValue(input.learnJson?.title, lang)
+    if (!title) {
+      plans.push({
+        lang,
+        kind: "skip",
+        detail: `Missing learn.json title for language "${lang}"`,
+      })
+      continue
+    }
+
+    const entry = resolution.byLang.get(canonicalLang(lang) as string)
+    if (!entry || entry.status === "unknown") {
+      plans.push({
+        lang,
+        kind: "skip",
+        detail: `${
+          entry?.status === "unknown" ?
+            entry.error :
+            "Existing asset could not be checked"
+        }; nothing was created or updated for this language to avoid duplicates.`,
+      })
+    } else if (entry.status === "ambiguous") {
+      plans.push({
+        lang,
+        kind: "skip",
+        detail: describeAmbiguity(lang, entry.candidates),
+      })
+    } else if (entry.status === "found") {
+      if (entry.asset.ownerId !== null && entry.asset.ownerId !== user.id) {
+        plans.push({
+          lang,
+          kind: "skip",
+          detail: `Asset #${entry.asset.id} ${entry.asset.slug} belongs to another user (owner ${entry.asset.ownerId}); it was not updated and no duplicate was created.`,
+        })
+      } else {
+        plans.push({
+          lang,
+          kind: "update",
+          asset: entry.asset,
+          slug: entry.asset.slug,
+        })
+      }
+    } else {
+      plans.push({ lang, kind: "create", slug: buildAssetSlug(title, lang) })
+    }
+  }
+
+  const allTranslations = plans
+    .filter(p => p.kind !== "skip")
+    .map(p => (p as { slug: string }).slug)
+
+  const rigoToken = input.rigoToken.trim()
+  const createdOrUpdatedIds: number[] = []
+
+  for (const plan of plans) {
+    if (plan.kind === "skip") {
+      errors.push(langError(plan.lang, plan.detail))
+      continue
+    }
+
+    const title = getLocalizedValue(input.learnJson?.title, plan.lang)
+    const description = getLocalizedValue(
+      input.learnJson?.description,
+      plan.lang
+    )
+
+    try {
+      if (plan.kind === "update") {
+        // Never send lang or slug: the language of an existing asset is not
+        // ours to change, and a slug would rename it.
+        const updatePayload: any = {
+          graded: true,
+          learnpack_deploy_url: input.deployUrl,
+          title,
+          category: "uncategorized",
+          description,
+          all_translations: allTranslations,
+          learnpack_id: learnpackId,
+        }
+        if (plan.asset.academyId === null && input.academyId !== undefined) {
+          updatePayload.academy_id = input.academyId
+        }
+
+        Console.info(
+          `Asset exists for "${plan.lang}" (#${plan.asset.id} ${plan.slug}), updating it`
+        )
+        // eslint-disable-next-line no-await-in-loop
+        const asset = await api.updateAsset(
+          input.bcToken,
+          plan.asset.id,
+          updatePayload
+        )
+        const id = typeof asset?.id === "number" ? asset.id : plan.asset.id
+        createdOrUpdatedIds.push(id)
+        synced.push({
+          lang: plan.lang,
+          action: "updated",
+          asset: { id, slug: asset?.slug ?? plan.slug },
+        })
+        continue
+      }
+
+      // eslint-disable-next-line no-await-in-loop
+      const readme = await input.readReadme(plan.lang)
+      const assetPayload: any = {
+        slug: plan.slug,
+        title,
+        lang: plan.lang,
+        graded: true,
+        description,
+        learnpack_deploy_url: input.deployUrl,
+        technologies: [],
+        url: input.deployUrl,
+        category: "uncategorized",
+        owner: user.id,
+        author: user.id,
+        preview: input.learnJson?.preview,
+        readme_raw: Buffer.from(readme).toString("base64"),
+        all_translations: allTranslations,
+        learnpack_id: learnpackId,
+      }
+      if (input.academyId !== undefined) {
+        assetPayload.academy_id = input.academyId
+      }
+
+      Console.info(`No asset for "${plan.lang}", creating ${plan.slug}`)
+      // eslint-disable-next-line no-await-in-loop
+      const asset = await api.createAsset(input.bcToken, assetPayload)
+      createdOrUpdatedIds.push(asset.id)
+      synced.push({
+        lang: plan.lang,
+        action: "created",
+        asset: { id: asset.id, slug: asset.slug ?? plan.slug },
+      })
+
+      // Record the id right away: a stale Breathecode cache could hide the
+      // new slug from the next publish, but the id never lies.
+      try {
+        // eslint-disable-next-line no-await-in-loop
+        await api.updateRigoPackage(rigoToken, input.packageSlug, {
+          asset_id: asset.id,
+        })
+      } catch (error) {
+        warnings.push(
+          `Could not record asset #${
+            asset.id
+          } in the Rigobot package: ${errorDetail(error)}`
+        )
+      }
+    } catch (error) {
+      const errorData =
+        error && typeof error === "object" && "response" in error ?
+          (error as any).response?.data || error :
+          error
+      Console.error(`Error syncing asset for language ${plan.lang}:`, error)
+      errors.push(langError(plan.lang, errorDetail(errorData)))
+    }
+  }
+
+  // Final list: everything Rigobot knew that still exists and is ours, plus
+  // whatever this run touched. Ids that 404 or belong to another package are
+  // the only ones that fall off; duplicates awaiting a manual decision stay.
+  const finalIds = [
+    ...new Set([
+      ...resolution.knownAssetIds,
+      ...resolution.orphanIds,
+      ...createdOrUpdatedIds,
+    ]),
+  ]
+  try {
+    await api.updateRigoPackage(rigoToken, input.packageSlug, {
+      asset_ids: finalIds,
+    })
+  } catch (error) {
+    warnings.push(
+      `Could not write asset_ids ${JSON.stringify(
+        finalIds
+      )} to the Rigobot package: ${errorDetail(error)}`
+    )
+  }
+
+  return { errors, warnings, synced }
+}

package/src/utils/awsCredentials.ts

@@ -1,57 +1,57 @@
-/**
- * AWS credentials for the published bucket, required rather than implicit.
- *
- * Building an `S3Client` with no credentials succeeds: the SDK defers to its
- * provider chain and only fails at the first request, with
- * "Could not load credentials from any providers". Inside a background job that
- * surfaces minutes later, detached from the cause. Validating up front turns it
- * into an obvious misconfiguration.
- *
- * Note this deliberately rejects the empty-string fallback pattern
- * (`process.env.X || ""`): passing empty credentials defeats the provider chain
- * instead of failing, which is how the opaque error appeared in the first place.
- */
-
-export type AwsCredentials = {
-  accessKeyId: string;
-  secretAccessKey: string;
-};
-
-export function requireAwsCredentials(): AwsCredentials {
-  const accessKeyId = (process.env.AWS_ACCESS_KEY_ID || "").trim()
-  const secretAccessKey = (process.env.AWS_SECRET_ACCESS_KEY || "").trim()
-
-  const missing: string[] = []
-  if (!accessKeyId) {
-    missing.push("AWS_ACCESS_KEY_ID")
-  }
-
-  if (!secretAccessKey) {
-    missing.push("AWS_SECRET_ACCESS_KEY")
-  }
-
-  if (missing.length > 0) {
-    throw new Error(
-      `${missing.join(" and ")} (env) ${
-        missing.length > 1 ? "are" : "is"
-      } required to reach the published package bucket`
-    )
-  }
-
-  return { accessKeyId, secretAccessKey }
-}
-
-export function requireS3PackagesBucket(): string {
-  const bucket = (process.env.S3_PACKAGES_BUCKET || "").trim()
-  if (!bucket) {
-    throw new Error(
-      "S3_PACKAGES_BUCKET (env) is required: it names the bucket holding published packages"
-    )
-  }
-
-  return bucket
-}
-
-export function awsRegion(): string {
-  return (process.env.AWS_REGION || "").trim() || "us-east-1"
-}
+/**
+ * AWS credentials for the published bucket, required rather than implicit.
+ *
+ * Building an `S3Client` with no credentials succeeds: the SDK defers to its
+ * provider chain and only fails at the first request, with
+ * "Could not load credentials from any providers". Inside a background job that
+ * surfaces minutes later, detached from the cause. Validating up front turns it
+ * into an obvious misconfiguration.
+ *
+ * Note this deliberately rejects the empty-string fallback pattern
+ * (`process.env.X || ""`): passing empty credentials defeats the provider chain
+ * instead of failing, which is how the opaque error appeared in the first place.
+ */
+
+export type AwsCredentials = {
+  accessKeyId: string;
+  secretAccessKey: string;
+};
+
+export function requireAwsCredentials(): AwsCredentials {
+  const accessKeyId = (process.env.AWS_ACCESS_KEY_ID || "").trim()
+  const secretAccessKey = (process.env.AWS_SECRET_ACCESS_KEY || "").trim()
+
+  const missing: string[] = []
+  if (!accessKeyId) {
+    missing.push("AWS_ACCESS_KEY_ID")
+  }
+
+  if (!secretAccessKey) {
+    missing.push("AWS_SECRET_ACCESS_KEY")
+  }
+
+  if (missing.length > 0) {
+    throw new Error(
+      `${missing.join(" and ")} (env) ${
+        missing.length > 1 ? "are" : "is"
+      } required to reach the published package bucket`
+    )
+  }
+
+  return { accessKeyId, secretAccessKey }
+}
+
+export function requireS3PackagesBucket(): string {
+  const bucket = (process.env.S3_PACKAGES_BUCKET || "").trim()
+  if (!bucket) {
+    throw new Error(
+      "S3_PACKAGES_BUCKET (env) is required: it names the bucket holding published packages"
+    )
+  }
+
+  return bucket
+}
+
+export function awsRegion(): string {
+  return (process.env.AWS_REGION || "").trim() || "us-east-1"
+}

package/src/utils/branding.ts

@@ -0,0 +1,78 @@
+/**
+ * Branding used by link previews (Open Graph / Twitter cards).
+ *
+ * Both the draft server and the publish pipeline need an absolute image URL for
+ * `og:image`, and drafts additionally need copy that says nothing about the
+ * course they belong to.
+ */
+
+/**
+ * Where `learnpack serve` runs in production. It is only a fallback: the server
+ * itself already has the real origin in `process.env.HOST` (it uses it to build
+ * webhook URLs). The `publish` command, however, runs on the author's machine
+ * with no such variable, and still has to write an absolute `og:image` into the
+ * package it uploads.
+ */
+export const PRODUCTION_PUBLIC_HOST = "https://app.learnpack.co"
+
+/**
+ * Strips what `.env` files routinely smuggle in — a trailing comment, quotes,
+ * stray whitespace, a trailing slash — the same way `serve` sanitises `HOST`.
+ * @param raw - The raw environment value, if set.
+ * @returns The cleaned value, or an empty string.
+ */
+function normalizeOrigin(raw?: string): string {
+  if (!raw) {
+    return ""
+  }
+
+  return raw
+    .trim()
+    .split(/\s+#/)[0]
+    .trim()
+    .replace(/["']/g, "")
+    .replace(/\/+$/, "")
+}
+
+/**
+ * Public origin of the app server, without a trailing slash.
+ *
+ * Only an absolute http(s) origin is accepted. `HOST` is also the conventional
+ * name for a bind address, so a deployment that sets it to `0.0.0.0` would
+ * otherwise yield a relative `og:image` — which no crawler can resolve, and
+ * which would be baked into every package published from that machine.
+ * @returns The origin to build absolute preview URLs from.
+ */
+export function getPublicHost(): string {
+  for (const raw of [process.env.PUBLIC_HOST, process.env.HOST]) {
+    const cleaned = normalizeOrigin(raw)
+    if (/^https?:\/\/\S+$/.test(cleaned)) {
+      return cleaned
+    }
+  }
+
+  return PRODUCTION_PUBLIC_HOST
+}
+
+/**
+ * Neutral brand card, used as `og:image` when a course has no preview of its own.
+ *
+ * It has to be a raster image: no unfurl crawler renders SVG. The previous
+ * fallback pointed at `learnpack.svg` on raw.githubusercontent.com, which fails
+ * twice over — SVG is unsupported, and that host serves it as `text/plain` with
+ * `X-Content-Type-Options: nosniff`.
+ */
+export function getFallbackPreviewUrl(): string {
+  return `${getPublicHost()}/og-image.png`
+}
+
+/**
+ * Copy for the link preview of a draft course.
+ *
+ * A draft is unlisted work in progress, so the card carries branding only: it
+ * must not disclose the title, the description or anything else about the
+ * course, and the pages that use it are served `noindex`.
+ */
+export const DRAFT_PREVIEW_TITLE = "LearnPack — Draft course"
+export const DRAFT_PREVIEW_DESCRIPTION =
+  "This course is still a draft and is not published yet."

package/src/utils/creatorUtilities.ts

@@ -134,6 +134,22 @@ export const slugify = (text: string) => {
     .replace(/^-+|-+$/g, "") // Trim hyphens from start/end
 }
 
+// Builds the slug of the Breathecode asset for a given title and language.
+// The backend only accepts letters, numbers, underscores and hyphens, so the
+// periods that slugify() keeps (e.g. "Next.js") are turned into hyphens here.
+// Hyphens are collapsed and trimmed BEFORE the 47-char cut on purpose: for a
+// title without periods this must yield exactly slugify(title).slice(0, 47),
+// which is the slug every existing asset was created with (a trailing hyphen
+// left by the cut is part of that historical slug and is kept).
+export const buildAssetSlug = (title: string, lang: string): string => {
+  const slug = slugify(title)
+    .replace(/\./g, "-")
+    .replace(/-+/g, "-")
+    .replace(/^-+|-+$/g, "")
+    .slice(0, 47)
+  return `${slug}-${lang}`
+}
+
 export const getExInfo = (title: string) => {
   // Example title: '1.0 - Introduction to AI [READ: Small introduction to important concepts such as AI, machine learning, and their applications]'
   let [exNumber, exTitle] = title.split(" - ")