@learnpack/learnpack 5.0.358 → 5.0.359

package/src/utils/api.ts

@@ -7,6 +7,7 @@ import * as dotenv from "dotenv"
 dotenv.config()
 
 const HOST = "https://breathecode.herokuapp.com"
+export const BREATHECODE_HOST = HOST
 
 /**
  * Student telemetry, and publication events. Both share the endpoint: a body
@@ -446,34 +447,66 @@ export type AssetSyncError =
   | { kind: "lang_error"; lang: string; error: { detail: string } }
   | { kind: "package_error"; error: { detail: string } };
 
-function parseLearnpackPackageId(raw: unknown): number | null {
-  if (raw === undefined || raw === null) return null
-  const n = typeof raw === "number" ? raw : Number(raw)
-  if (!Number.isFinite(n) || !Number.isInteger(n)) return null
-  return n
+export type RigoPackageLookup =
+  | { kind: "found"; id: number; assetIds: number[] }
+  | { kind: "missing" }
+  | { kind: "error"; error: string };
+
+/**
+ * Human-readable summary of a failed axios call, for warnings and error payloads.
+ * @param error - Whatever the request rejected with.
+ * @returns "HTTP <status>" when the server answered, the error message otherwise.
+ */
+export function describeRequestError(error: unknown): string {
+  if (axios.isAxiosError(error)) {
+    if (error.response) {
+      const detail =
+        error.response.data?.detail ?? error.response.data?.error ?? ""
+      return `HTTP ${error.response.status}${detail ? ` (${detail})` : ""}`
+    }
+
+    return error.message
+  }
+
+  return error instanceof Error ? error.message : String(error)
 }
 
 /**
- * GET Rigobot package by slug after a successful upload. Does not throw.
- * @param rigoToken Rigobot API token (Bearer-style `Token` header value).
+ * GET a Rigobot package by slug. Distinguishes "no such package" from
+ * "could not check", so callers can fail closed on the latter.
+ * @param rigoToken Rigobot API token (`Token` header value).
  * @param courseSlug Learnpack package slug used in the Rigobot URL path.
- * @returns Resolved numeric package id from Rigobot, or `null` if the request fails, the id is missing, or it is not a finite integer.
+ * @returns The package id and its asset_ids, `missing` on 404, `error` otherwise (403 included: a package owned by somebody else is not ours to read).
  */
-export async function resolveLearnpackPackageId(
+export async function getRigoPackage(
   rigoToken: string,
   courseSlug: string
-): Promise<number | null> {
-  if (!rigoToken?.trim() || !courseSlug) return null
+): Promise<RigoPackageLookup> {
+  const cleanToken = rigoToken.replace(/[\n\r]/g, "").trim()
   const url = `${RIGOBOT_HOST}/v1/learnpack/package/${encodeURIComponent(
     courseSlug
   )}/`
   try {
-    const response = await axios.get<{ id?: unknown }>(url, {
-      headers: { Authorization: `Token ${rigoToken.trim()}` },
+    const response = await axios.get(url, {
+      headers: { Authorization: `Token ${cleanToken}` },
     })
-    return parseLearnpackPackageId(response.data?.id)
-  } catch {
-    return null
+    const rawId = response.data?.id
+    const id = typeof rawId === "number" ? rawId : Number(rawId)
+    if (!Number.isInteger(id)) {
+      return { kind: "error", error: "Rigobot package has no numeric id" }
+    }
+
+    const rawIds = response.data?.asset_ids
+    const assetIds: number[] = Array.isArray(rawIds) ?
+      rawIds.filter((x: unknown): x is number => Number.isInteger(x)) :
+      []
+    return { kind: "found", id, assetIds }
+  } catch (error) {
+    if (axios.isAxiosError(error) && error.response?.status === 404) {
+      return { kind: "missing" }
+    }
+
+    return { kind: "error", error: describeRequestError(error) }
   }
 }
 
@@ -556,52 +589,125 @@ export const createAsset = async (token: string, asset: TAssetMissing) => {
   }
 }
 
-export const doesAssetExists = async (
-  token: string,
-  assetSlug: string
-): Promise<{ exists: boolean; academyId?: number }> => {
-  const url = `https://breathecode.herokuapp.com/v1/registry/asset/${assetSlug}`
+/** The subset of a Breathecode asset the publish flow reads. */
+export type BcAsset = {
+  id: number;
+  slug: string;
+  lang: string | null;
+  status: string | null;
+  learnpackId: number | null;
+  learnpackDeployUrl: string | null;
+  ownerId: number | null;
+  academyId: number | null;
+};
 
-  const headers = {
-    Authorization: `Token ${token}`,
+export type AssetLookup =
+  | { kind: "found"; asset: BcAsset }
+  | { kind: "missing" }
+  | { kind: "error"; error: string };
+
+const asIntegerOrNull = (raw: unknown): number | null => {
+  if (raw === null || raw === undefined || raw === "") return null
+  const n = typeof raw === "number" ? raw : Number(raw)
+  return Number.isInteger(n) ? n : null
+}
+
+const toBcAsset = (data: any): BcAsset | null => {
+  if (!data || typeof data !== "object") return null
+  const id = asIntegerOrNull(data.id)
+  if (id === null || typeof data.slug !== "string") return null
+  return {
+    id,
+    slug: data.slug,
+    lang: typeof data.lang === "string" && data.lang ? data.lang : null,
+    status: typeof data.status === "string" ? data.status : null,
+    learnpackId: asIntegerOrNull(data.learnpack_id),
+    learnpackDeployUrl:
+      typeof data.learnpack_deploy_url === "string" ?
+        data.learnpack_deploy_url :
+        null,
+    ownerId: asIntegerOrNull(data.owner?.id ?? data.owner),
+    academyId: asIntegerOrNull(data.academy?.id ?? data.academy_id),
   }
+}
 
+const lookupAsset = async (
+  token: string,
+  slugOrId: string
+): Promise<AssetLookup> => {
+  const url = `${HOST}/v1/registry/asset/${encodeURIComponent(slugOrId)}`
   try {
-    const response = await axios.get(url, { headers })
-    if (response.status === 200) {
-      const academyId = response.data?.academy?.id || response.data?.academy_id
-      return { exists: true, academyId }
+    const response = await axios.get(url, {
+      headers: { Authorization: `Token ${token}` },
+    })
+    const asset = toBcAsset(response.data)
+    if (asset === null) {
+      // A 200 that is not an asset (e.g. the readme renderer answering for a
+      // path with a period) proves nothing either way: fail closed.
+      return {
+        kind: "error",
+        error: `Unexpected response for asset ${slugOrId}`,
+      }
     }
 
-    return { exists: false }
-  } catch {
-    // console.error("Failed to get asset:", error)
-    return { exists: false }
+    return { kind: "found", asset }
+  } catch (error) {
+    if (axios.isAxiosError(error) && error.response?.status === 404) {
+      return { kind: "missing" }
+    }
+
+    return { kind: "error", error: describeRequestError(error) }
   }
 }
 
+/**
+ * GET a Breathecode asset by numeric id. The endpoint applies no status or
+ * visibility filter for a single asset, so this is the stable anchor.
+ * @param token Breathecode token.
+ * @param assetId Asset primary key.
+ * @returns `found` with the asset, `missing` on 404, `error` when it could not be checked.
+ */
+export const getAssetById = (token: string, assetId: number) =>
+  lookupAsset(token, String(assetId))
+
+/**
+ * GET a Breathecode asset by slug.
+ * @param token Breathecode token.
+ * @param assetSlug Asset slug.
+ * @returns `found` with the asset, `missing` on 404, `error` when it could not be checked.
+ */
+export const getAssetBySlug = (token: string, assetSlug: string) =>
+  lookupAsset(token, assetSlug)
+
 const updateAsset = async (
   token: string,
-  assetSlug: string,
+  assetId: number,
   asset: Partial<TAssetMissing> & { learnpack_id: number }
 ) => {
-  const url = `https://breathecode.herokuapp.com/v1/registry/asset/me/${assetSlug}`
+  // The list form of PUT /asset/me updates by id, so a slug rename or an
+  // alias never sends the update to the wrong asset.
+  const url = `${HOST}/v1/registry/asset/me`
   const headers = {
     Authorization: `Token ${token}`,
   }
 
-  const body = { ...asset, learnpack_id: asset.learnpack_id }
+  const body = [{ ...asset, id: assetId, learnpack_id: asset.learnpack_id }]
 
-  console.log("[BC] PUT", url, "| academy_id:", asset.academy_id ?? "none")
+  console.log(
+    "[BC] PUT",
+    url,
+    "| id:",
+    assetId,
+    "| academy_id:",
+    asset.academy_id ?? "none"
+  )
 
   try {
     const response = await axios.put(url, body, { headers })
-    return response.data
+    return Array.isArray(response.data) ? response.data[0] : response.data
   } catch (error: any) {
     console.error("Failed to update asset:", error)
-    // Try to print the data
-    // console.log(error.response.data)
-    throw error.response.data
+    throw error.response?.data ?? error
   }
 }
 
@@ -619,10 +725,18 @@ const getCategories = async (token: string) => {
   }
 }
 
+/**
+ * PUT on the Rigobot package. `asset_id` appends one id to asset_ids (Rigobot
+ * side), `asset_ids` replaces the whole list.
+ * @param token Rigobot token.
+ * @param slug Package slug.
+ * @param updates Fields to write.
+ * @returns The updated package payload.
+ */
 const updateRigoPackage = async (
   token: string,
   slug: string,
-  updates: { asset_id?: number; new_slug?: string }
+  updates: { asset_id?: number; asset_ids?: number[] }
 ) => {
   const cleanToken = token.replace(/[\n\r]/g, "")
 
@@ -755,9 +869,10 @@ export default {
   listUserAcademies,
   validateToken,
   createAsset,
-  doesAssetExists,
+  getAssetById,
+  getAssetBySlug,
   updateAsset,
-  resolveLearnpackPackageId,
+  getRigoPackage,
   getCategories,
   updateRigoPackage,
   createRigoPackage,

package/src/utils/assetResolver.ts

@@ -0,0 +1,368 @@
+/**
+ * Resolves which Breathecode assets already represent a Learnpack package,
+ * one per language, before publish decides whether to create or update.
+ *
+ * The anchor is the package's `asset_ids` in Rigobot, read back by id from
+ * Breathecode. The title-derived slug is only a fallback for packages that
+ * predate `asset_ids`; it is never the criterion for a package whose ids are
+ * known. Every "could not check" outcome is reported as such, never as "does
+ * not exist", so a network hiccup cannot turn into a duplicate asset.
+ */
+import api, { BcAsset } from "./api"
+import { buildAssetSlug } from "./creatorUtilities"
+
+export type LangResolution =
+  | { status: "found"; asset: BcAsset; via: "id" | "slug" }
+  | { status: "missing" }
+  | { status: "ambiguous"; candidates: BcAsset[] }
+  | { status: "unknown"; error: string };
+
+export type PackageAssetsResolution = {
+  packageSlug: string;
+  /** Rigobot package id, or null when the package does not exist yet (or no Rigobot token was given). */
+  learnpackId: number | null;
+  /** `unknown` when Rigobot or Breathecode could not be read: nothing may be created or written. */
+  packageState: "ok" | "unknown";
+  packageError?: string;
+  /** Ids from Rigobot that still resolve to an asset of this package. */
+  knownAssetIds: number[];
+  /** Ids from Rigobot whose asset has no language: never adopted, but never dropped either. */
+  orphanIds: number[];
+  /** Keyed by canonical language (see canonicalLang). */
+  byLang: Map<string, LangResolution>;
+  warnings: string[];
+};
+
+export type AcademyMode =
+  | { type: "select" }
+  | { type: "locked"; academyId: number }
+  | { type: "conflict"; academies: number[] };
+
+/**
+ * Breathecode stores "en" as "us"; both name the same language.
+ * @param lang - Language code as found in learn.json or on an asset.
+ * @returns The canonical code, or null when there is none.
+ */
+export const canonicalLang = (lang?: string | null): string | null => {
+  if (typeof lang !== "string") return null
+  const lower = lang.trim().toLowerCase()
+  if (!lower) return null
+  return lower === "en" ? "us" : lower
+}
+
+/**
+ * Language keys of learn.json.title, in declaration order.
+ * @param learnJson - Parsed learn.json.
+ * @returns Non-empty string keys of `title`.
+ */
+export const getAvailableLangs = (learnJson: any): string[] => {
+  const langs = Object.keys(learnJson?.title || {})
+  return langs.filter(l => typeof l === "string" && l.length > 0)
+}
+
+/**
+ * Drops keys that name the same language ("en" and "us"), keeping "en" when
+ * both are present and the first one declared otherwise.
+ * @param langs - Language keys as declared in learn.json.
+ * @returns One key per canonical language.
+ */
+export const dedupeLangs = (langs: string[]): string[] => {
+  const byCanonical = new Map<string, string>()
+  for (const lang of langs) {
+    const canonical = canonicalLang(lang)
+    if (canonical === null) continue
+    const current = byCanonical.get(canonical)
+    if (current === undefined || (lang === "en" && current === "us")) {
+      byCanonical.set(canonical, lang)
+    }
+  }
+
+  return [...byCanonical.values()]
+}
+
+/**
+ * Slugs an asset for this language may have been created under.
+ *
+ * One per learn.json title naming this language (title.en and title.us can
+ * differ, and a historical asset came from whichever existed at the time),
+ * each with both suffixes when the language is "us"/"en".
+ * @param learnJson - Parsed learn.json.
+ * @param canonical - Canonical language.
+ * @returns Distinct candidate slugs, most likely first.
+ */
+export const slugCandidatesForLang = (
+  learnJson: any,
+  canonical: string
+): string[] => {
+  const suffixes = canonical === "us" ? ["en", "us"] : [canonical]
+  const seen = new Set<string>()
+  const out: string[] = []
+  for (const key of getAvailableLangs(learnJson)) {
+    if (canonicalLang(key) !== canonical) continue
+    const title = learnJson.title[key]
+    if (typeof title !== "string" || !title.trim()) continue
+    for (const suffix of suffixes) {
+      const slug = buildAssetSlug(title, suffix)
+      if (!seen.has(slug)) {
+        seen.add(slug)
+        out.push(slug)
+      }
+    }
+  }
+
+  return out
+}
+
+const describeAsset = (asset: BcAsset): string =>
+  `#${asset.id} ${asset.slug} (${asset.status ?? "?"}${
+    asset.academyId === null ? "" : `, academy ${asset.academyId}`
+  })`
+
+/**
+ * Text for the error a language gets when more than one asset claims it.
+ * @param lang - Language key from learn.json.
+ * @param candidates - The competing assets.
+ * @returns An actionable message naming every candidate.
+ */
+export const describeAmbiguity = (
+  lang: string,
+  candidates: BcAsset[]
+): string =>
+  `Found ${
+    candidates.length
+  } Breathecode assets for language "${lang}": ${candidates
+    .map(describeAsset)
+    .join(
+      "; "
+    )}. Nothing was created or updated for this language. Keep only the definitive ids in the Rigobot package (asset_ids) and publish again.`
+
+export type ResolverApi = {
+  getRigoPackage: typeof api.getRigoPackage;
+  getAssetById: typeof api.getAssetById;
+  getAssetBySlug: typeof api.getAssetBySlug;
+};
+
+export type ResolveInput = {
+  bcToken: string;
+  /** Optional: without it only the slug fallback runs (older IDEs do not send it). */
+  rigoToken?: string;
+  packageSlug: string;
+  learnJson: any;
+  deps?: ResolverApi;
+};
+
+/**
+ * Resolves the existing Breathecode asset for every language of a package.
+ * @param input - Tokens, package slug and parsed learn.json.
+ * @returns Per-language resolution plus the package-level facts publish needs.
+ */
+export async function resolvePackageAssets(
+  input: ResolveInput
+): Promise<PackageAssetsResolution> {
+  const deps = input.deps ?? api
+  const warnings: string[] = []
+  const langs = dedupeLangs(getAvailableLangs(input.learnJson))
+  const byLang = new Map<string, LangResolution>()
+
+  const unknownEverywhere = (
+    error: string,
+    learnpackId: number | null
+  ): PackageAssetsResolution => {
+    for (const lang of langs) {
+      byLang.set(canonicalLang(lang) as string, { status: "unknown", error })
+    }
+
+    return {
+      packageSlug: input.packageSlug,
+      learnpackId,
+      packageState: "unknown",
+      packageError: error,
+      knownAssetIds: [],
+      orphanIds: [],
+      byLang,
+      warnings,
+    }
+  }
+
+  // Step 0: the package in Rigobot, and the asset ids it already knows.
+  let learnpackId: number | null = null
+  let previousIds: number[] = []
+  if (input.rigoToken?.trim()) {
+    const pkg = await deps.getRigoPackage(input.rigoToken, input.packageSlug)
+    if (pkg.kind === "error") {
+      return unknownEverywhere(
+        `Could not read the Rigobot package "${input.packageSlug}": ${pkg.error}`,
+        null
+      )
+    }
+
+    if (pkg.kind === "found") {
+      learnpackId = pkg.id
+      previousIds = [...new Set(pkg.assetIds)]
+    }
+  } else {
+    warnings.push(
+      "No Rigobot token: existing assets are looked up by slug only."
+    )
+  }
+
+  // Step 1: read every known id back from Breathecode.
+  const knownAssetIds: number[] = []
+  const orphanIds: number[] = []
+  const candidatesByLang = new Map<string, BcAsset[]>()
+  for (const id of previousIds) {
+    // eslint-disable-next-line no-await-in-loop
+    const lookup = await deps.getAssetById(input.bcToken, id)
+    if (lookup.kind === "error") {
+      return unknownEverywhere(
+        `Could not read Breathecode asset #${id}: ${lookup.error}`,
+        learnpackId
+      )
+    }
+
+    if (lookup.kind === "missing") {
+      warnings.push(
+        `Asset #${id} listed in the Rigobot package no longer exists in Breathecode; dropped.`
+      )
+      continue
+    }
+
+    const asset = lookup.asset
+    if (
+      asset.learnpackId !== null &&
+      learnpackId !== null &&
+      asset.learnpackId !== learnpackId
+    ) {
+      warnings.push(
+        `Asset ${describeAsset(asset)} belongs to Learnpack package ${
+          asset.learnpackId
+        }, not ${learnpackId}; ignored.`
+      )
+      continue
+    }
+
+    const canonical = canonicalLang(asset.lang)
+    if (canonical === null) {
+      orphanIds.push(asset.id)
+      warnings.push(
+        `Asset ${describeAsset(
+          asset
+        )} has no language; kept in the package but not used.`
+      )
+      continue
+    }
+
+    knownAssetIds.push(asset.id)
+    const group = candidatesByLang.get(canonical) ?? []
+    group.push(asset)
+    candidatesByLang.set(canonical, group)
+  }
+
+  // Step 2: languages with no known id fall back to the title-derived slugs.
+  for (const lang of langs) {
+    const canonical = canonicalLang(lang) as string
+    const known = candidatesByLang.get(canonical) ?? []
+    if (known.length === 1) {
+      byLang.set(canonical, { status: "found", asset: known[0], via: "id" })
+      continue
+    }
+
+    if (known.length > 1) {
+      byLang.set(canonical, { status: "ambiguous", candidates: known })
+      continue
+    }
+
+    const found = new Map<number, BcAsset>()
+    let error: string | null = null
+    for (const slug of slugCandidatesForLang(input.learnJson, canonical)) {
+      // eslint-disable-next-line no-await-in-loop
+      const lookup = await deps.getAssetBySlug(input.bcToken, slug)
+      if (lookup.kind === "error") {
+        error = `Could not check Breathecode asset "${slug}": ${lookup.error}`
+        break
+      }
+
+      if (lookup.kind === "missing") continue
+      const asset = lookup.asset
+      if (
+        asset.learnpackId !== null &&
+        learnpackId !== null &&
+        asset.learnpackId !== learnpackId
+      ) {
+        warnings.push(
+          `Asset ${describeAsset(
+            asset
+          )} matches the slug for "${lang}" but belongs to Learnpack package ${
+            asset.learnpackId
+          }; ignored.`
+        )
+        continue
+      }
+
+      found.set(asset.id, asset)
+    }
+
+    if (error !== null) {
+      byLang.set(canonical, { status: "unknown", error })
+    } else if (found.size === 0) {
+      byLang.set(canonical, { status: "missing" })
+    } else if (found.size === 1) {
+      const asset = [...found.values()][0]
+      if (previousIds.length > 0) {
+        warnings.push(
+          `Asset ${describeAsset(
+            asset
+          )} for "${lang}" was found by slug, not through the Rigobot package; it will be added to asset_ids.`
+        )
+      }
+
+      byLang.set(canonical, { status: "found", asset, via: "slug" })
+    } else {
+      byLang.set(canonical, {
+        status: "ambiguous",
+        candidates: [...found.values()],
+      })
+    }
+  }
+
+  return {
+    packageSlug: input.packageSlug,
+    learnpackId,
+    packageState: "ok",
+    knownAssetIds,
+    orphanIds,
+    byLang,
+    warnings,
+  }
+}
+
+/**
+ * Academy handling for the publish prompt, from the assets that were found.
+ * @param resolution - Output of resolvePackageAssets.
+ * @returns `select` when no found asset has an academy, `locked` when they all share one, `conflict` otherwise.
+ */
+export const determineAcademyMode = (
+  resolution: PackageAssetsResolution
+): AcademyMode => {
+  const academyIds: number[] = []
+  for (const entry of resolution.byLang.values()) {
+    if (entry.status === "found" && entry.asset.academyId !== null) {
+      academyIds.push(entry.asset.academyId)
+    }
+  }
+
+  const unique = [...new Set(academyIds)]
+  if (unique.length === 0) return { type: "select" }
+  if (unique.length === 1) return { type: "locked", academyId: unique[0] }
+  return { type: "conflict", academies: unique }
+}
+
+/**
+ * Whether at least one language already has an asset.
+ * @param resolution - Output of resolvePackageAssets.
+ * @returns True when any language resolved to `found`.
+ */
+export const hasPublishedAsset = (
+  resolution: PackageAssetsResolution
+): boolean =>
+  [...resolution.byLang.values()].some(entry => entry.status === "found")