@learnpack/learnpack 5.0.358 → 5.0.359

package/lib/utils/api.js

@@ -1,7 +1,8 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.getCurrentTechnologies = exports.fetchTechnologies = exports.doesAssetExists = exports.createAsset = exports.validateToken = exports.listUserAcademies = exports.getConsumable = exports.countConsumables = exports.RIGOBOT_REALTIME_HOST = exports.RIGOBOT_HOST = exports.BREATHECODE_EVENTS_URL = exports.BREATHECODE_TELEMETRY_URL = void 0;
-exports.resolveLearnpackPackageId = resolveLearnpackPackageId;
+exports.getCurrentTechnologies = exports.fetchTechnologies = exports.getAssetBySlug = exports.getAssetById = exports.createAsset = exports.validateToken = exports.listUserAcademies = exports.getConsumable = exports.countConsumables = exports.RIGOBOT_REALTIME_HOST = exports.RIGOBOT_HOST = exports.BREATHECODE_EVENTS_URL = exports.BREATHECODE_TELEMETRY_URL = exports.BREATHECODE_HOST = void 0;
+exports.describeRequestError = describeRequestError;
+exports.getRigoPackage = getRigoPackage;
 const console_1 = require("../utils/console");
 const storage = require("node-persist");
 const cli_ux_1 = require("cli-ux");
@@ -9,6 +10,7 @@ const axios_1 = require("axios");
 const dotenv = require("dotenv");
 dotenv.config();
 const HOST = "https://breathecode.herokuapp.com";
+exports.BREATHECODE_HOST = HOST;
 /**
  * Student telemetry, and publication events. Both share the endpoint: a body
  * carrying a top-level `event` key is dispatched as an event, anything else
@@ -349,33 +351,53 @@ const validateToken = async (token) => {
     }
 };
 exports.validateToken = validateToken;
-function parseLearnpackPackageId(raw) {
-    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;
+/**
+ * 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.
+ */
+function describeRequestError(error) {
+    var _a, _b, _c, _d;
+    if (axios_1.default.isAxiosError(error)) {
+        if (error.response) {
+            const detail = (_d = (_b = (_a = error.response.data) === null || _a === void 0 ? void 0 : _a.detail) !== null && _b !== void 0 ? _b : (_c = error.response.data) === null || _c === void 0 ? void 0 : _c.error) !== null && _d !== void 0 ? _d : "";
+            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).
  */
-async function resolveLearnpackPackageId(rigoToken, courseSlug) {
-    var _a;
-    if (!(rigoToken === null || rigoToken === void 0 ? void 0 : rigoToken.trim()) || !courseSlug)
-        return null;
+async function getRigoPackage(rigoToken, courseSlug) {
+    var _a, _b, _c;
+    const cleanToken = rigoToken.replace(/[\n\r]/g, "").trim();
     const url = `${exports.RIGOBOT_HOST}/v1/learnpack/package/${encodeURIComponent(courseSlug)}/`;
     try {
         const response = await axios_1.default.get(url, {
-            headers: { Authorization: `Token ${rigoToken.trim()}` },
+            headers: { Authorization: `Token ${cleanToken}` },
         });
-        return parseLearnpackPackageId((_a = response.data) === null || _a === void 0 ? void 0 : _a.id);
+        const rawId = (_a = response.data) === null || _a === void 0 ? void 0 : _a.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 = (_b = response.data) === null || _b === void 0 ? void 0 : _b.asset_ids;
+        const assetIds = Array.isArray(rawIds) ?
+            rawIds.filter((x) => Number.isInteger(x)) :
+            [];
+        return { kind: "found", id, assetIds };
     }
-    catch (_b) {
-        return null;
+    catch (error) {
+        if (axios_1.default.isAxiosError(error) && ((_c = error.response) === null || _c === void 0 ? void 0 : _c.status) === 404) {
+            return { kind: "missing" };
+        }
+        return { kind: "error", error: describeRequestError(error) };
     }
 }
 const createAsset = async (token, asset) => {
@@ -429,43 +451,91 @@ const createAsset = async (token, asset) => {
     }
 };
 exports.createAsset = createAsset;
-const doesAssetExists = async (token, assetSlug) => {
-    var _a, _b, _c;
-    const url = `https://breathecode.herokuapp.com/v1/registry/asset/${assetSlug}`;
-    const headers = {
-        Authorization: `Token ${token}`,
+const asIntegerOrNull = (raw) => {
+    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) => {
+    var _a, _b, _c, _d;
+    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((_b = (_a = data.owner) === null || _a === void 0 ? void 0 : _a.id) !== null && _b !== void 0 ? _b : data.owner),
+        academyId: asIntegerOrNull((_d = (_c = data.academy) === null || _c === void 0 ? void 0 : _c.id) !== null && _d !== void 0 ? _d : data.academy_id),
     };
+};
+const lookupAsset = async (token, slugOrId) => {
+    var _a;
+    const url = `${HOST}/v1/registry/asset/${encodeURIComponent(slugOrId)}`;
     try {
-        const response = await axios_1.default.get(url, { headers });
-        if (response.status === 200) {
-            const academyId = ((_b = (_a = response.data) === null || _a === void 0 ? void 0 : _a.academy) === null || _b === void 0 ? void 0 : _b.id) || ((_c = response.data) === null || _c === void 0 ? void 0 : _c.academy_id);
-            return { exists: true, academyId };
+        const response = await axios_1.default.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 };
+        return { kind: "found", asset };
     }
-    catch (_d) {
-        // console.error("Failed to get asset:", error)
-        return { exists: false };
+    catch (error) {
+        if (axios_1.default.isAxiosError(error) && ((_a = error.response) === null || _a === void 0 ? void 0 : _a.status) === 404) {
+            return { kind: "missing" };
+        }
+        return { kind: "error", error: describeRequestError(error) };
     }
 };
-exports.doesAssetExists = doesAssetExists;
-const updateAsset = async (token, assetSlug, asset) => {
-    var _a;
-    const url = `https://breathecode.herokuapp.com/v1/registry/asset/me/${assetSlug}`;
+/**
+ * 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.
+ */
+const getAssetById = (token, assetId) => lookupAsset(token, String(assetId));
+exports.getAssetById = getAssetById;
+/**
+ * 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.
+ */
+const getAssetBySlug = (token, assetSlug) => lookupAsset(token, assetSlug);
+exports.getAssetBySlug = getAssetBySlug;
+const updateAsset = async (token, assetId, asset) => {
+    var _a, _b, _c;
+    // 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 = Object.assign(Object.assign({}, asset), { learnpack_id: asset.learnpack_id });
-    console.log("[BC] PUT", url, "| academy_id:", (_a = asset.academy_id) !== null && _a !== void 0 ? _a : "none");
+    const body = [Object.assign(Object.assign({}, asset), { id: assetId, learnpack_id: asset.learnpack_id })];
+    console.log("[BC] PUT", url, "| id:", assetId, "| academy_id:", (_a = asset.academy_id) !== null && _a !== void 0 ? _a : "none");
     try {
         const response = await axios_1.default.put(url, body, { headers });
-        return response.data;
+        return Array.isArray(response.data) ? response.data[0] : response.data;
     }
     catch (error) {
         console.error("Failed to update asset:", error);
-        // Try to print the data
-        // console.log(error.response.data)
-        throw error.response.data;
+        throw (_c = (_b = error.response) === null || _b === void 0 ? void 0 : _b.data) !== null && _c !== void 0 ? _c : error;
     }
 };
 const getCategories = async (token) => {
@@ -482,6 +552,14 @@ const getCategories = async (token) => {
         throw error;
     }
 };
+/**
+ * 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, slug, updates) => {
     const cleanToken = token.replace(/[\n\r]/g, "");
     const url = `${exports.RIGOBOT_HOST}/v1/learnpack/package/${slug}/`;
@@ -588,9 +666,10 @@ exports.default = {
     listUserAcademies: exports.listUserAcademies,
     validateToken: exports.validateToken,
     createAsset: exports.createAsset,
-    doesAssetExists: exports.doesAssetExists,
+    getAssetById: exports.getAssetById,
+    getAssetBySlug: exports.getAssetBySlug,
     updateAsset,
-    resolveLearnpackPackageId,
+    getRigoPackage,
     getCategories,
     updateRigoPackage,
     createRigoPackage,

package/lib/utils/assetResolver.d.ts

@@ -0,0 +1,116 @@
+/**
+ * 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";
+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 declare const canonicalLang: (lang?: string | null) => string | null;
+/**
+ * Language keys of learn.json.title, in declaration order.
+ * @param learnJson - Parsed learn.json.
+ * @returns Non-empty string keys of `title`.
+ */
+export declare const getAvailableLangs: (learnJson: any) => string[];
+/**
+ * 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 declare const dedupeLangs: (langs: string[]) => string[];
+/**
+ * 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 declare const slugCandidatesForLang: (learnJson: any, canonical: string) => string[];
+/**
+ * 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 declare const describeAmbiguity: (lang: string, candidates: BcAsset[]) => string;
+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 declare function resolvePackageAssets(input: ResolveInput): Promise<PackageAssetsResolution>;
+/**
+ * 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 declare const determineAcademyMode: (resolution: PackageAssetsResolution) => AcademyMode;
+/**
+ * Whether at least one language already has an asset.
+ * @param resolution - Output of resolvePackageAssets.
+ * @returns True when any language resolved to `found`.
+ */
+export declare const hasPublishedAsset: (resolution: PackageAssetsResolution) => boolean;

package/lib/utils/assetResolver.js

@@ -0,0 +1,268 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.hasPublishedAsset = exports.determineAcademyMode = exports.describeAmbiguity = exports.slugCandidatesForLang = exports.dedupeLangs = exports.getAvailableLangs = exports.canonicalLang = void 0;
+exports.resolvePackageAssets = resolvePackageAssets;
+/**
+ * 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.
+ */
+const api_1 = require("./api");
+const creatorUtilities_1 = require("./creatorUtilities");
+/**
+ * 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.
+ */
+const canonicalLang = (lang) => {
+    if (typeof lang !== "string")
+        return null;
+    const lower = lang.trim().toLowerCase();
+    if (!lower)
+        return null;
+    return lower === "en" ? "us" : lower;
+};
+exports.canonicalLang = canonicalLang;
+/**
+ * Language keys of learn.json.title, in declaration order.
+ * @param learnJson - Parsed learn.json.
+ * @returns Non-empty string keys of `title`.
+ */
+const getAvailableLangs = (learnJson) => {
+    const langs = Object.keys((learnJson === null || learnJson === void 0 ? void 0 : learnJson.title) || {});
+    return langs.filter(l => typeof l === "string" && l.length > 0);
+};
+exports.getAvailableLangs = getAvailableLangs;
+/**
+ * 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.
+ */
+const dedupeLangs = (langs) => {
+    const byCanonical = new Map();
+    for (const lang of langs) {
+        const canonical = (0, exports.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()];
+};
+exports.dedupeLangs = dedupeLangs;
+/**
+ * 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.
+ */
+const slugCandidatesForLang = (learnJson, canonical) => {
+    const suffixes = canonical === "us" ? ["en", "us"] : [canonical];
+    const seen = new Set();
+    const out = [];
+    for (const key of (0, exports.getAvailableLangs)(learnJson)) {
+        if ((0, exports.canonicalLang)(key) !== canonical)
+            continue;
+        const title = learnJson.title[key];
+        if (typeof title !== "string" || !title.trim())
+            continue;
+        for (const suffix of suffixes) {
+            const slug = (0, creatorUtilities_1.buildAssetSlug)(title, suffix);
+            if (!seen.has(slug)) {
+                seen.add(slug);
+                out.push(slug);
+            }
+        }
+    }
+    return out;
+};
+exports.slugCandidatesForLang = slugCandidatesForLang;
+const describeAsset = (asset) => {
+    var _a;
+    return `#${asset.id} ${asset.slug} (${(_a = asset.status) !== null && _a !== void 0 ? _a : "?"}${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.
+ */
+const describeAmbiguity = (lang, candidates) => `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.`;
+exports.describeAmbiguity = describeAmbiguity;
+/**
+ * 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.
+ */
+async function resolvePackageAssets(input) {
+    var _a, _b, _c, _d;
+    const deps = (_a = input.deps) !== null && _a !== void 0 ? _a : api_1.default;
+    const warnings = [];
+    const langs = (0, exports.dedupeLangs)((0, exports.getAvailableLangs)(input.learnJson));
+    const byLang = new Map();
+    const unknownEverywhere = (error, learnpackId) => {
+        for (const lang of langs) {
+            byLang.set((0, exports.canonicalLang)(lang), { 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 = null;
+    let previousIds = [];
+    if ((_b = input.rigoToken) === null || _b === void 0 ? void 0 : _b.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 = [];
+    const orphanIds = [];
+    const candidatesByLang = new Map();
+    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 = (0, exports.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 = (_c = candidatesByLang.get(canonical)) !== null && _c !== void 0 ? _c : [];
+        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 = (0, exports.canonicalLang)(lang);
+        const known = (_d = candidatesByLang.get(canonical)) !== null && _d !== void 0 ? _d : [];
+        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();
+        let error = null;
+        for (const slug of (0, exports.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.
+ */
+const determineAcademyMode = (resolution) => {
+    const academyIds = [];
+    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 };
+};
+exports.determineAcademyMode = determineAcademyMode;
+/**
+ * Whether at least one language already has an asset.
+ * @param resolution - Output of resolvePackageAssets.
+ * @returns True when any language resolved to `found`.
+ */
+const hasPublishedAsset = (resolution) => [...resolution.byLang.values()].some(entry => entry.status === "found");
+exports.hasPublishedAsset = hasPublishedAsset;

package/lib/utils/assetSync.d.ts

@@ -0,0 +1,48 @@
+/**
+ * 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 { AssetSyncError } from "./api";
+import { PackageAssetsResolution } 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 declare const getLocalizedValue: (translations: Record<string, any> | undefined, lang: string) => string;
+/**
+ * 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 declare function syncPackageAssets(input: AssetSyncInput): Promise<AssetSyncResult>;