@learnpack/learnpack 5.0.363 → 5.0.364

package/lib/models/creator.d.ts

@@ -36,6 +36,7 @@ export interface Lesson {
             startedAt: number;
             completedAt?: number;
             error?: boolean;
+            autoRetries?: number;
             description?: string | null;
             descriptionStatus?: "generated" | "pending" | "error" | "none";
             sourceContentHash?: string;

package/lib/utils/generationRetry.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Automatic retries for the two lesson generation phases. Without a cap, an
+ * error that always repeats, like a broken prompt template, starts jobs
+ * forever: Rigobot fails in under a second and the webhook starts another one.
+ */
+/** Automatic retries allowed per phase, after the first job. */
+export declare const MAX_AUTO_RETRIES = 2;
+/**
+ * Whether a failed job would fail the same way if started again.
+ * @param statusText - The `status_text` Rigobot sends with the error.
+ * @returns True when retrying cannot help.
+ */
+export declare const isPermanentGenerationError: (statusText: unknown) => boolean;
+type LessonState = {
+    status?: string;
+    translations?: {
+        [language: string]: {
+            completionId?: number;
+            autoRetries?: number;
+        };
+    };
+};
+/**
+ * Whether a webhook belongs to a job the lesson no longer waits for. That
+ * happens when Rigobot sends a second webhook for a finished job, or when an
+ * old job answers after a newer one started.
+ * @param lesson - The lesson as saved in the syllabus.
+ * @param language - The course language.
+ * @param jobId - The id of the job the webhook reports.
+ * @returns True when the webhook must not change the lesson.
+ */
+export declare const isStaleWebhook: (lesson: LessonState, language: string, jobId: unknown) => boolean;
+export type RetryPlan = {
+    retry: true;
+    attempt: number;
+} | {
+    retry: false;
+    reason: "permanent" | "exhausted";
+};
+/**
+ * Decides whether a failed job starts another one.
+ * @param lesson - The lesson as saved in the syllabus.
+ * @param language - The course language.
+ * @param statusText - The `status_text` Rigobot sends with the error.
+ * @returns The retry to start, numbered from 1, or why there is none.
+ */
+export declare const planGenerationRetry: (lesson: LessonState, language: string, statusText: unknown) => RetryPlan;
+export {};

package/lib/utils/generationRetry.js

@@ -0,0 +1,81 @@
+"use strict";
+/**
+ * Automatic retries for the two lesson generation phases. Without a cap, an
+ * error that always repeats, like a broken prompt template, starts jobs
+ * forever: Rigobot fails in under a second and the webhook starts another one.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.planGenerationRetry = exports.isStaleWebhook = exports.isPermanentGenerationError = exports.MAX_AUTO_RETRIES = void 0;
+/** Automatic retries allowed per phase, after the first job. */
+exports.MAX_AUTO_RETRIES = 2;
+/**
+ * Errors from Rigobot that repeat on every attempt, so retrying only spends
+ * jobs. They come from the template, the inputs or the model configuration.
+ */
+const PERMANENT_ERRORS = [
+    // A template placeholder without an input.
+    /^Missing key /,
+    // Braces in a template body that Python's str.format cannot parse.
+    /format string|in field name|out of range for positional args/,
+    // The purpose's engine cannot return the template's fields.
+    /doesn't support structured outputs/,
+    // The model API rejected the request itself. 429 and 5xx are not here,
+    // because they can pass.
+    /^Error code: (400|401|403|404|422)\b/,
+];
+/**
+ * Whether a failed job would fail the same way if started again.
+ * @param statusText - The `status_text` Rigobot sends with the error.
+ * @returns True when retrying cannot help.
+ */
+const isPermanentGenerationError = (statusText) => {
+    if (typeof statusText !== "string")
+        return false;
+    const text = statusText.trim();
+    // A Python KeyError prints as its quoted key: a placeholder in the template
+    // that matches no input.
+    if (/^["']/.test(text) || text.startsWith("{'"))
+        return true;
+    return PERMANENT_ERRORS.some(pattern => pattern.test(text));
+};
+exports.isPermanentGenerationError = isPermanentGenerationError;
+/**
+ * Whether a webhook belongs to a job the lesson no longer waits for. That
+ * happens when Rigobot sends a second webhook for a finished job, or when an
+ * old job answers after a newer one started.
+ * @param lesson - The lesson as saved in the syllabus.
+ * @param language - The course language.
+ * @param jobId - The id of the job the webhook reports.
+ * @returns True when the webhook must not change the lesson.
+ */
+const isStaleWebhook = (lesson, language, jobId) => {
+    var _a, _b;
+    if (lesson.status === "DONE")
+        return true;
+    const current = (_b = (_a = lesson.translations) === null || _a === void 0 ? void 0 : _a[language]) === null || _b === void 0 ? void 0 : _b.completionId;
+    // Job ids grow, so a lower id is an older job. Without both ids, nothing
+    // tells the webhook apart, and it is handled.
+    return (typeof jobId === "number" &&
+        typeof current === "number" &&
+        current > 0 &&
+        jobId < current);
+};
+exports.isStaleWebhook = isStaleWebhook;
+/**
+ * Decides whether a failed job starts another one.
+ * @param lesson - The lesson as saved in the syllabus.
+ * @param language - The course language.
+ * @param statusText - The `status_text` Rigobot sends with the error.
+ * @returns The retry to start, numbered from 1, or why there is none.
+ */
+const planGenerationRetry = (lesson, language, statusText) => {
+    var _a, _b, _c;
+    if ((0, exports.isPermanentGenerationError)(statusText)) {
+        return { retry: false, reason: "permanent" };
+    }
+    const used = (_c = (_b = (_a = lesson.translations) === null || _a === void 0 ? void 0 : _a[language]) === null || _b === void 0 ? void 0 : _b.autoRetries) !== null && _c !== void 0 ? _c : 0;
+    if (used >= exports.MAX_AUTO_RETRIES)
+        return { retry: false, reason: "exhausted" };
+    return { retry: true, attempt: used + 1 };
+};
+exports.planGenerationRetry = planGenerationRetry;

package/lib/utils/interactivity/componentsGuide.d.ts

@@ -0,0 +1,50 @@
+import { DecidedBy } from "./structuredComponents";
+export declare const COMPONENTS_V2_URL = "https://raw.githubusercontent.com/learnpack/ide/refs/heads/master/docs/components_v2.yml";
+export interface GuideComponent {
+    name: string;
+    category: string;
+    decidedBy: DecidedBy;
+    choose: {
+        summary: string;
+        goodFor?: string[];
+        avoid?: string[];
+        tests?: string[];
+    };
+    write: {
+        fields: Record<string, string>;
+        rules?: string[];
+    };
+    visualStyle?: string;
+}
+export interface ComponentsGuide {
+    version: string;
+    components: GuideComponent[];
+}
+export declare class ComponentsGuideUnavailableError extends Error {
+    constructor(message: string);
+}
+export declare const parseComponentsGuide: (text: string) => {
+    guide: ComponentsGuide;
+    warnings: string[];
+};
+export declare const buildInteractivityGuide: (guide: ComponentsGuide) => string;
+export declare const decidedByFromGuide: (guide: ComponentsGuide) => Record<string, DecidedBy>;
+type Fetcher = (url: string, timeoutMs: number) => Promise<string>;
+export declare const resolveComponentsGuideUrl: (env?: Record<string, string | undefined>) => string;
+export interface GuideLoaderOptions {
+    url?: string;
+    fetcher?: Fetcher;
+    timeoutMs?: number;
+    retryDelaysMs?: number[];
+    maxAgeMs?: number;
+    now?: () => number;
+    sleep?: (ms: number) => Promise<void>;
+    log?: (message: string) => void;
+}
+export interface GuideLoader {
+    load(): Promise<ComponentsGuide>;
+    peek(): ComponentsGuide | null;
+}
+export declare const createGuideLoader: (options?: GuideLoaderOptions) => GuideLoader;
+export declare const componentsGuideLoader: GuideLoader;
+export {};

package/lib/utils/interactivity/componentsGuide.js

@@ -0,0 +1,193 @@
+"use strict";
+// Loads docs/components_v2.yml from learnpack/ide and turns it into the
+// COMPONENTS input of the structured interactivity template.
+//
+// The file is the single source of truth for component names and for the
+// guidance the model receives. Without it the model does not know what each
+// field means, so a generation must not start when no valid copy is available.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.componentsGuideLoader = exports.createGuideLoader = exports.resolveComponentsGuideUrl = exports.decidedByFromGuide = exports.buildInteractivityGuide = exports.parseComponentsGuide = exports.ComponentsGuideUnavailableError = exports.COMPONENTS_V2_URL = void 0;
+const axios_1 = require("axios");
+const yaml = require("js-yaml");
+const structuredComponents_1 = require("./structuredComponents");
+exports.COMPONENTS_V2_URL = "https://raw.githubusercontent.com/learnpack/ide/refs/heads/master/docs/components_v2.yml";
+class ComponentsGuideUnavailableError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "ComponentsGuideUnavailableError";
+        Object.setPrototypeOf(this, ComponentsGuideUnavailableError.prototype);
+    }
+}
+exports.ComponentsGuideUnavailableError = ComponentsGuideUnavailableError;
+const isNonEmptyString = (value) => typeof value === "string" && value.trim().length > 0;
+const isPlainObject = (value) => value !== null && typeof value === "object" && !Array.isArray(value);
+// Parses and checks the guide. It is lenient on purpose: the IDE repository
+// can add or rename a component before this CLI knows it, and that must not
+// stop every generation. Unknown or incomplete components are skipped with a
+// warning; the guide is unavailable only when it does not parse or has no
+// usable component.
+const parseComponentsGuide = (text) => {
+    let document;
+    try {
+        document = yaml.load(text);
+    }
+    catch (error) {
+        throw new ComponentsGuideUnavailableError(`components_v2.yml is not valid YAML: ${error.message}`);
+    }
+    if (!isPlainObject(document) || !Array.isArray(document.components)) {
+        throw new ComponentsGuideUnavailableError("components_v2.yml has no components list");
+    }
+    const warnings = [];
+    const known = new Set(structuredComponents_1.COMPONENT_NAMES);
+    const seen = new Set();
+    const components = [];
+    for (const raw of document.components) {
+        const name = isPlainObject(raw) && isNonEmptyString(raw.name) ? raw.name : "(no name)";
+        if (!known.has(name)) {
+            warnings.push(`components_v2.yml: "${name}" is not a component this CLI can render; skipped`);
+            continue;
+        }
+        if (seen.has(name)) {
+            warnings.push(`components_v2.yml: "${name}" appears twice; the second one is skipped`);
+            continue;
+        }
+        const decidedBy = raw.decidedBy;
+        if ((decidedBy !== "syllabus" && decidedBy !== "interactivity") ||
+            !isPlainObject(raw.choose) ||
+            !isNonEmptyString(raw.choose.summary) ||
+            !isPlainObject(raw.write) ||
+            !isPlainObject(raw.write.fields)) {
+            warnings.push(`components_v2.yml: "${name}" lacks decidedBy, choose.summary or write.fields; skipped`);
+            continue;
+        }
+        seen.add(name);
+        components.push(raw);
+    }
+    if (components.length === 0) {
+        throw new ComponentsGuideUnavailableError("components_v2.yml has no usable component");
+    }
+    for (const name of structuredComponents_1.COMPONENT_NAMES) {
+        if (!seen.has(name)) {
+            warnings.push(`components_v2.yml: "${name}" is missing; the model can still return it, without guidance`);
+        }
+    }
+    return {
+        guide: { version: String(document.version || ""), components },
+        warnings,
+    };
+};
+exports.parseComponentsGuide = parseComponentsGuide;
+// The COMPONENTS input of the template: what each field means and the
+// writing rules, plus the choice criteria. Full criteria only go to the
+// components this step decides; for the ones the syllabus plans, the summary
+// is enough to pick a format when a step has no plan. Syntax never goes in.
+const buildInteractivityGuide = (guide) => {
+    const components = guide.components.map(component => {
+        const choose = component.decidedBy === "interactivity" ?
+            component.choose :
+            { summary: component.choose.summary };
+        const entry = {
+            name: component.name,
+            choose,
+            write: component.write,
+        };
+        return entry;
+    });
+    return yaml.dump({ components }, { lineWidth: -1, noRefs: true });
+};
+exports.buildInteractivityGuide = buildInteractivityGuide;
+const decidedByFromGuide = (guide) => {
+    const result = {};
+    for (const component of guide.components)
+        result[component.name] = component.decidedBy;
+    return result;
+};
+exports.decidedByFromGuide = decidedByFromGuide;
+const defaultFetcher = async (url, timeoutMs) => {
+    const response = await axios_1.default.get(url, {
+        timeout: timeoutMs,
+        responseType: "text",
+        transformResponse: [(data) => data],
+    });
+    return String(response.data);
+};
+// Where the guide is downloaded from. COMPONENTS_V2_URL overrides master, for
+// example with the raw URL of a branch, to test a guide before merging it:
+// master is read by every hosted generation. Never set it in production.
+const resolveComponentsGuideUrl = (env = process.env) => env.COMPONENTS_V2_URL || exports.COMPONENTS_V2_URL;
+exports.resolveComponentsGuideUrl = resolveComponentsGuideUrl;
+// Keeps the last valid copy in memory (per process). A copy older than
+// maxAgeMs is still served while a new one is fetched in the background
+// (stale-while-revalidate), so a GitHub hiccup does not stop a generation that
+// already had the guide. Concurrent calls share one download.
+const createGuideLoader = (options = {}) => {
+    var _a, _b;
+    const fetcher = options.fetcher || defaultFetcher;
+    const timeoutMs = (_a = options.timeoutMs) !== null && _a !== void 0 ? _a : 5000;
+    const retryDelaysMs = options.retryDelaysMs || [1000, 2000];
+    const maxAgeMs = (_b = options.maxAgeMs) !== null && _b !== void 0 ? _b : 10 * 60 * 1000;
+    const now = options.now || Date.now;
+    const sleep = options.sleep ||
+        ((ms) => new Promise(resolve => {
+            setTimeout(resolve, ms);
+        }));
+    const log = options.log || ((message) => console.warn(message));
+    let cached = null;
+    let inFlight = null;
+    const fetchAndParse = async () => {
+        const url = options.url || (0, exports.resolveComponentsGuideUrl)();
+        if (url !== exports.COMPONENTS_V2_URL) {
+            log(`Loading the components guide from ${url} instead of master`);
+        }
+        let lastError = "unknown error";
+        for (let attempt = 0; attempt <= retryDelaysMs.length; attempt++) {
+            // eslint-disable-next-line no-await-in-loop -- attempts are sequential on purpose
+            if (attempt > 0)
+                await sleep(retryDelaysMs[attempt - 1]);
+            let text;
+            try {
+                // eslint-disable-next-line no-await-in-loop -- attempts are sequential on purpose
+                text = await fetcher(url, timeoutMs);
+            }
+            catch (error) {
+                lastError = `could not download ${url}: ${error.message}`;
+                continue;
+            }
+            // A file that does not parse will not parse on the next attempt either.
+            const { guide, warnings } = (0, exports.parseComponentsGuide)(text);
+            for (const warning of warnings)
+                log(warning);
+            return guide;
+        }
+        throw new ComponentsGuideUnavailableError(lastError);
+    };
+    const refresh = () => {
+        if (!inFlight) {
+            inFlight = fetchAndParse().then(guide => {
+                cached = { guide, fetchedAt: now() };
+                inFlight = null;
+                return guide;
+            }, error => {
+                inFlight = null;
+                throw error;
+            });
+        }
+        return inFlight;
+    };
+    return {
+        async load() {
+            if (cached) {
+                if (now() - cached.fetchedAt > maxAgeMs) {
+                    refresh().catch(error => log(`Could not refresh the components guide, using the copy in memory: ${error.message}`));
+                }
+                return cached.guide;
+            }
+            return refresh();
+        },
+        peek() {
+            return cached ? cached.guide : null;
+        },
+    };
+};
+exports.createGuideLoader = createGuideLoader;
+exports.componentsGuideLoader = (0, exports.createGuideLoader)();

package/lib/utils/interactivity/interactivityPlan.d.ts

@@ -0,0 +1,20 @@
+export declare const INTERACTIVITY_V1_SLUG = "add-lesson-interactivy";
+export declare const INTERACTIVITY_V2_SLUG = "add-lesson-interactivity-v2";
+export type InteractivityTemplate = "v1" | "v2";
+export declare const isInteractivityV2Enabled: (env?: Record<string, string | undefined>) => boolean;
+export interface InteractivityRequest {
+    tpl: InteractivityTemplate;
+    slug: string;
+    webhookQuery: string;
+}
+export declare const planInteractivityRequest: ({ v2Enabled, forceV1, }: {
+    v2Enabled: boolean;
+    forceV1?: boolean;
+}) => InteractivityRequest;
+export interface InteractivityFailure {
+    fromV2: boolean;
+    retryStatusText: unknown;
+}
+export declare const describeInteractivityFailure: (query: {
+    tpl?: unknown;
+}, statusText: unknown) => InteractivityFailure;

package/lib/utils/interactivity/interactivityPlan.js

@@ -0,0 +1,33 @@
+"use strict";
+// Which interactivity template a lesson uses, and what happens when it fails.
+//
+// v2 (structured) returns component data that the CLI renders; v1 is the
+// original template, which writes the component markdown itself. The webhook
+// URL carries the template, because rigobot posts back to that exact URL and
+// its error payload does not say it. How many retries a lesson gets is decided
+// by utils/generationRetry.ts, as for the other generation phases.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.describeInteractivityFailure = exports.planInteractivityRequest = exports.isInteractivityV2Enabled = exports.INTERACTIVITY_V2_SLUG = exports.INTERACTIVITY_V1_SLUG = void 0;
+exports.INTERACTIVITY_V1_SLUG = "add-lesson-interactivy";
+exports.INTERACTIVITY_V2_SLUG = "add-lesson-interactivity-v2";
+const isInteractivityV2Enabled = (env = process.env) => env.INTERACTIVITY_V2 === "true";
+exports.isInteractivityV2Enabled = isInteractivityV2Enabled;
+const planInteractivityRequest = ({ v2Enabled, forceV1 = false, }) => {
+    const tpl = v2Enabled && !forceV1 ? "v2" : "v1";
+    return {
+        tpl,
+        slug: tpl === "v2" ? exports.INTERACTIVITY_V2_SLUG : exports.INTERACTIVITY_V1_SLUG,
+        webhookQuery: `?tpl=${tpl}`,
+    };
+};
+exports.planInteractivityRequest = planInteractivityRequest;
+// After a failed job. Every retry uses v1, so a problem of the new template
+// never blocks a lesson. An error that would repeat normally stops the retries,
+// but when the v2 template fails that says nothing about v1, so the error is
+// not passed on and v1 gets its retry within the usual cap. Jobs started
+// before this change have no query and count as v1.
+const describeInteractivityFailure = (query, statusText) => {
+    const fromV2 = query.tpl === "v2";
+    return { fromV2, retryStatusText: fromV2 ? undefined : statusText };
+};
+exports.describeInteractivityFailure = describeInteractivityFailure;

package/lib/utils/interactivity/structuredComponents.d.ts

@@ -0,0 +1,34 @@
+export declare const COMPONENT_NAMES: readonly ["multiple_choice_question", "select_the_blank", "ordering", "open_text_question", "code_challenge_proposal", "ask_rigo_button", "mermaid_diagram", "technical_diagram", "conceptual_illustration", "realistic_photography"];
+export type ComponentName = typeof COMPONENT_NAMES[number];
+export type DecidedBy = "syllabus" | "interactivity";
+export declare const DEFAULT_DECIDED_BY: Record<ComponentName, DecidedBy>;
+export interface Issue {
+    component?: ComponentName;
+    id?: string;
+    message: string;
+}
+export interface ProcessContext {
+    stepType?: string;
+    isFirstOrLast?: boolean;
+    lessonId?: string;
+    decidedBy?: Partial<Record<string, DecidedBy>>;
+}
+export interface ProcessResult {
+    markdown: string;
+    usedComponents: ComponentName[];
+    assessmentCount: number;
+    dropped: Issue[];
+    warnings: Issue[];
+}
+export declare const collapse: (value: unknown) => string;
+export declare const stripBlockPrefix: (value: unknown) => string;
+export declare const encodeMetaValue: (value: unknown) => string;
+export declare const fence: (language: string, meta: string, body: string) => string;
+export declare const toSlug: (value: string) => string;
+export declare const seededShuffle: <T>(items: T[], seed: string) => T[];
+export declare const removeCopiedSyntax: (text: string) => {
+    text: string;
+    removed: string[];
+};
+export declare const processInteractivityResult: (parsed: any, ctx?: ProcessContext) => ProcessResult;
+export declare const isImageComponent: (name: string) => boolean;