utn-mcp 0.8.3 → 0.9.1

package/build/autogestion/login.js

@@ -0,0 +1,59 @@
+import { ask, askChoice, askHidden } from "../shared/input.js";
+import { logger } from "../shared/logger.js";
+import { catalogEntryForRegional } from "./client/catalog.js";
+import { connectorKit, systemForRegional, UnsupportedRegionalError } from "./client/connector.js";
+import { saveAutogestionCredentials } from "./client/credentials.js";
+import { installConnector, installedManifest } from "./client/install.js";
+import { loadInstalledSystems } from "./client/installed-systems.js";
+/**
+ * `utn-mcp login autogestion`: instala el conector de la regional si falta o quedó viejo, pide legajo
+ * y contraseña, los prueba contra el sistema y recién ahí los guarda en el keychain. La misma regional
+ * que se usa para el aula decide qué sistema de autogestión toca.
+ */
+export async function runAutogestionLogin(regionalId) {
+    const entry = catalogEntryForRegional(regionalId);
+    if (entry && (await installedManifest(entry))?.version !== entry.version) {
+        logger.info(`Bajando el conector de ${entry.name}...`);
+        await installConnector(entry);
+    }
+    const system = systemForRegional(regionalId, await loadInstalledSystems());
+    if (!system)
+        throw new UnsupportedRegionalError(regionalId);
+    if (entry?.regionales[regionalId] === "candidate") {
+        logger.info(`El conector de ${system.name} todavía no se probó en tu regional: si algo no anda, contalo en ` +
+            "https://github.com/nialvape/utn-mcp/issues.");
+    }
+    const hint = system.usernameHint?.(regionalId);
+    const username = (await ask(`Legajo o usuario de ${system.name}${hint ? ` (${hint})` : ""}: `)).trim();
+    if (!username)
+        throw new Error("Falta el usuario.");
+    const password = await askHidden("Contraseña: ");
+    // Se guardan recién después de comprobar que el sistema las aceptó.
+    const connector = system.create(regionalId, connectorKit);
+    await connector.login({ username, password });
+    if (await saveAutogestionCredentials(system.id, { username, password })) {
+        logger.info("Credenciales guardadas en el keychain del sistema.");
+    }
+    else {
+        logger.warn("No hay keychain disponible: definí las variables de entorno del sistema (ver README).");
+    }
+    logger.info(`Listo: ${system.name} conectado.`);
+}
+/**
+ * Después del login del aula: si la regional tiene un conector en el catálogo, ofrece conectarlo.
+ * Un error acá no deshace el login del aula, que ya quedó guardado.
+ */
+export async function offerAutogestionLogin(regionalId) {
+    const entry = catalogEntryForRegional(regionalId);
+    if (!entry)
+        return;
+    const options = ["Sí", "No, después con `utn-mcp login autogestion`"];
+    if ((await askChoice(`¿Conectar también ${entry.name} (estado académico, correlativas, finales)?`, options)) !== 0)
+        return;
+    try {
+        await runAutogestionLogin(regionalId);
+    }
+    catch (e) {
+        logger.warn(`${e.message}\nEl aula quedó conectada; ${entry.name} se puede conectar después con \`utn-mcp login autogestion\`.`);
+    }
+}

package/build/autogestion/tools.d.ts

@@ -0,0 +1,3 @@
+import type { McpServer } from "@modelcontextprotocol/server";
+import type { AutogestionSession } from "./client/session.js";
+export declare function registerAutogestionTools(server: McpServer, session: AutogestionSession): void;

package/build/autogestion/tools.js

@@ -0,0 +1,73 @@
+import { getCorrelatividades } from "./format/correlatividades.js";
+import { getEstadoAcademico } from "./format/estado-academico.js";
+import { getExamenes } from "./format/examenes.js";
+import { getCursandoAhora } from "./format/notas-parciales.js";
+// JSON compacto: indentar estas respuestas cuesta ~25% más de contexto y no se lee mejor.
+const json = (data) => ({
+    content: [{ type: "text", text: JSON.stringify(data) }],
+});
+const failure = (e) => ({
+    content: [{ type: "text", text: `Error: ${e.message}` }],
+    isError: true,
+});
+/** Igual para todas: el login es distinto en local (CLI) y en HTTP (link), así que lo explica el error. */
+const LOGIN_NOTE = " Si todavía no entró a su autogestión, el error dice cómo hacerlo; seguilo. Las credenciales son las del " +
+    "sistema de autogestión, que no siempre son las del aula virtual.";
+export function registerAutogestionTools(server, session) {
+    server.registerTool("autogestion_estado_academico", {
+        description: "Estado académico del usuario según la autogestión de su regional: cada materia OBLIGATORIA " +
+            "del plan con su estado (regular, aprobada, libre), plan, nota y fecha. No es el catálogo " +
+            "completo de la carrera: puede incluir electivas aprobadas y no listar materias sin " +
+            "movimientos cargados. Las que se están cursando se marcan como Cursando cuando el " +
+            "sistema permite saberlas." + LOGIN_NOTE,
+        annotations: { readOnlyHint: true, openWorldHint: false },
+    }, async () => {
+        try {
+            return json(await getEstadoAcademico(session));
+        }
+        catch (e) {
+            return failure(e);
+        }
+    });
+    server.registerTool("autogestion_cursando_ahora", {
+        description: "Materias que el usuario está cursando ahora según la autogestión de su regional, con su " +
+            "comisión, aula y horarios cuando el sistema los publica. Incluye electivas, a diferencia " +
+            "del estado académico." + LOGIN_NOTE,
+        annotations: { readOnlyHint: true, openWorldHint: false },
+    }, async () => {
+        try {
+            return json(await getCursandoAhora(session));
+        }
+        catch (e) {
+            return failure(e);
+        }
+    });
+    server.registerTool("autogestion_examenes", {
+        description: "Historial de exámenes finales del usuario según la autogestión de su regional: fecha, " +
+            "materia, nota o estado del examen cuando todavía no hay nota, plan y código. Puede cubrir " +
+            "también materias rendidas en planes anteriores y electivas que el estado académico no " +
+            "muestra." + LOGIN_NOTE,
+        annotations: { readOnlyHint: true, openWorldHint: false },
+    }, async () => {
+        try {
+            return json(await getExamenes(session));
+        }
+        catch (e) {
+            return failure(e);
+        }
+    });
+    server.registerTool("autogestion_correlatividades", {
+        description: "Correlatividades de la carrera del usuario según la autogestión de su regional, separadas " +
+            "para cursar y para rendir cuando el sistema las distingue: para cada materia, qué exige " +
+            "tener regular o aprobada. Es la fuente dinámica de " +
+            "correlatividades: usala en lugar de suponer datos de un plan fijo." + LOGIN_NOTE,
+        annotations: { readOnlyHint: true, openWorldHint: false },
+    }, async () => {
+        try {
+            return json(await getCorrelatividades(session));
+        }
+        catch (e) {
+            return failure(e);
+        }
+    });
+}

package/build/http.d.ts

@@ -0,0 +1,26 @@
+import { type AuthInfo, type McpServerFactory } from "@modelcontextprotocol/server";
+import type { StoredAutogestion } from "./autogestion/client/stored-session.js";
+import type { AccessPolicy } from "./oauth/access.js";
+import type { RedirectAllowlist } from "./oauth/redirects.js";
+import type { SessionStore } from "./shared/store/session-store.js";
+import { type UploadInbox } from "./shared/uploads.js";
+/** El usuario del store dueño del token, en `extra.userId`. */
+export declare function userIdOf(authInfo: AuthInfo | undefined): number;
+/** Dónde escucha el servidor y, si está publicado, desde qué dirección lo ven los clientes. */
+export interface HttpOptions {
+    host: string;
+    port: number;
+    /** Sin barra final, por ejemplo `https://mcp.tu-dominio.com`. */
+    publicUrl?: string;
+    /** Quién puede conectarse por OAuth. */
+    access: AccessPolicy;
+    /** A dónde puede volver el navegador después del login de OAuth. */
+    redirects: RedirectAllowlist;
+    /** Con él se habilita la API de /admin (ver `mountAdmin`). */
+    adminSecret?: string;
+}
+/**
+ * El factory recibe en `ctx.authInfo` el token ya validado, con el usuario; de ahí arma su sesión.
+ * `autogestion` sirve la página donde cada usuario entra a la autogestión de su regional.
+ */
+export declare function startHttpServer(factory: McpServerFactory, options: HttpOptions, store: SessionStore, inbox: UploadInbox, autogestion: StoredAutogestion): void;

package/build/http.js

@@ -2,6 +2,7 @@ import express from "express";
 import { Readable } from "node:stream";
 import { bearerAuthChallengeResponse, createMcpHandler, OAuthError, OAuthErrorCode, verifyBearerToken, } from "@modelcontextprotocol/server";
 import { hostHeaderValidation, originValidation, toNodeHandler } from "@modelcontextprotocol/node";
+import { mountAutogestionLink } from "./autogestion/link-page.js";
 import { mountAdmin } from "./oauth/admin.js";
 import { cors, mountOAuth } from "./oauth/server.js";
 import { logger } from "./shared/logger.js";
@@ -41,8 +42,11 @@ function storeVerifier(store) {
     };
 }
 const LOOPBACK = ["localhost", "127.0.0.1", "[::1]"];
-/** El factory recibe en `ctx.authInfo` el token ya validado, con el usuario; de ahí arma su sesión. */
-export function startHttpServer(factory, options, store, inbox) {
+/**
+ * El factory recibe en `ctx.authInfo` el token ya validado, con el usuario; de ahí arma su sesión.
+ * `autogestion` sirve la página donde cada usuario entra a la autogestión de su regional.
+ */
+export function startHttpServer(factory, options, store, inbox, autogestion) {
     const { host, port, publicUrl, access, redirects, adminSecret } = options;
     const handler = createMcpHandler(factory, { onerror: (e) => logger.error(e.message) });
     const verifier = storeVerifier(store);
@@ -99,6 +103,7 @@ export function startHttpServer(factory, options, store, inbox) {
         res.type("html").send(page(upload.title, uploadForm(upload.limits)));
     });
     app.post("/subir/:id", sameOrigin, (req, res) => receiveUpload(inbox, req, res));
+    mountAutogestionLink(app, autogestion, sameOrigin);
     app.listen(port, host, () => {
         logger.info(`Servidor MCP escuchando en http://${host}:${port}/mcp`);
         if (publicUrl)

package/build/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+import "./shared/load-env.js";

package/build/index.js

@@ -6,6 +6,11 @@ import { LocalSession } from "./aula-virtual/client/local-session.js";
 import { defaultRegional } from "./aula-virtual/client/regionals.js";
 import { StoredAulaSession } from "./aula-virtual/client/stored-session.js";
 import { runLogin } from "./aula-virtual/login.js";
+import { installCatalog } from "./autogestion/client/install.js";
+import { loadInstalledSystems } from "./autogestion/client/installed-systems.js";
+import { LocalAutogestionSession } from "./autogestion/client/local-session.js";
+import { StoredAutogestion } from "./autogestion/client/stored-session.js";
+import { offerAutogestionLogin, runAutogestionLogin } from "./autogestion/login.js";
 import { startHttpServer, userIdOf } from "./http.js";
 import { accessPolicyFromEnv } from "./oauth/access.js";
 import { redirectAllowlistFromEnv } from "./oauth/redirects.js";
@@ -18,6 +23,7 @@ const USAGE = `Uso:
   utn-mcp --http [--host H] [--port N]  servidor MCP por HTTP (por defecto 127.0.0.1:3000)
   utn-mcp login           guardar credenciales de la UTN y obtener el primer token
   utn-mcp login --http    lo mismo, para el modo HTTP: guarda la sesión y emite el token del cliente
+  utn-mcp login autogestion  instalar el conector de la autogestión de tu regional y guardar legajo y contraseña
 
 Si hay un .env en la carpeta actual, se lee al arrancar (ver .env.example).`;
 async function main() {
@@ -38,7 +44,15 @@ async function main() {
     // Una UTN_REGIONAL que no existe corta acá: si no, recién fallaría al primer login o al primer pedido.
     defaultRegional();
     if (positionals[0] === "login") {
-        await runLogin(values.http);
+        if (positionals[1] === "autogestion") {
+            await runAutogestionLogin((await new LocalSession().getRegional()).id);
+        }
+        else {
+            await runLogin(values.http);
+            // En HTTP cada usuario entra a su autogestión desde el link que le pasa el agente.
+            if (!values.http)
+                await offerAutogestionLogin((await new LocalSession().getRegional()).id);
+        }
         return;
     }
     if (values.http) {
@@ -51,10 +65,13 @@ async function main() {
         const loginUrl = process.env.UTN_MCP_LOGIN_URL || `${baseUrl}/login`;
         const store = await SqliteStore.open();
         const inbox = new UploadInbox(baseUrl);
+        // Atiende a usuarios de cualquier regional: se instalan todos los conectores del catálogo.
+        await installCatalog();
+        const autogestion = new StoredAutogestion(baseUrl, store, await loadSystems());
         const factory = (ctx) => {
             const userId = userIdOf(ctx.authInfo);
             const aula = new StoredAulaSession(store, userId, loginUrl);
-            return createServer(aula, { local: false, inbox, owner: String(userId) });
+            return createServer(aula, { local: false, inbox, owner: String(userId) }, autogestion.forUser(userId));
         };
         const options = {
             host: values.host,
@@ -64,15 +81,29 @@ async function main() {
             redirects: redirectAllowlistFromEnv(),
             adminSecret: process.env.UTN_MCP_ADMIN_SECRET || undefined,
         };
-        startHttpServer(factory, options, store, inbox);
+        startHttpServer(factory, options, store, inbox, autogestion);
     }
     else {
         // STDIO: un solo usuario, el de la compu, con la misma sesión para todas las conexiones.
         const aula = new LocalSession();
-        serveStdio(() => createServer(aula, { local: true }), { onerror: (e) => logger.error(e.message) });
+        const autogestion = {
+            systems: await loadSystems(),
+            sessionFor: (system, regionalId) => new LocalAutogestionSession(system, regionalId),
+        };
+        serveStdio(() => createServer(aula, { local: true }, autogestion), { onerror: (e) => logger.error(e.message) });
         logger.info("Servidor MCP iniciado en STDIO");
     }
 }
+/** Los conectores de autogestión instalados. Uno roto no puede dejar sin aula virtual: si falla, se sigue sin ellos. */
+async function loadSystems() {
+    try {
+        return await loadInstalledSystems();
+    }
+    catch (e) {
+        logger.warn(e.message);
+        return [];
+    }
+}
 main().catch((e) => {
     logger.error(e.message);
     process.exit(1);

package/build/oauth/access.d.ts

@@ -0,0 +1,18 @@
+export type AccessDecision = {
+    allowed: true;
+} | {
+    allowed: false;
+    reason: string;
+    url?: string;
+};
+/** Quién puede usar el servidor: decide con el usuario que acaba de entrar al aula de su regional. */
+export type AccessPolicy = (user: {
+    regional: string;
+    username: string;
+    email: string | null;
+}) => Promise<AccessDecision>;
+/**
+ * La política sale del entorno: con UTN_MCP_ACCESS_URL decide otro servicio;
+ * con UTN_MCP_ALLOWED_EMAILS, una lista; sin ninguna, entra cualquiera con usuario de la UTN.
+ */
+export declare function accessPolicyFromEnv(env?: NodeJS.ProcessEnv): AccessPolicy;

package/build/oauth/admin.d.ts

@@ -0,0 +1,8 @@
+import { type Express } from "express";
+import type { SessionStore } from "../shared/store/session-store.js";
+/**
+ * API para que otro servicio del que hostea (un panel de cuenta, por ejemplo) liste usuarios, muestre y
+ * desconecte sus apps, consulte las regionales y dé de alta cuentas vinculando su aula. Solo
+ * existe con UTN_MCP_ADMIN_SECRET, que va como `Authorization: Bearer`. Los usuarios se buscan por email.
+ */
+export declare function mountAdmin(app: Express, store: SessionStore, secret: string): void;

package/build/oauth/admin.js

@@ -5,7 +5,7 @@ import { availableRegionals } from "../aula-virtual/client/regionals.js";
 import { InvalidCredentialsError, MfaError } from "../aula-virtual/client/sso-login.js";
 import { AULA_PLATFORM } from "../aula-virtual/client/stored-session.js";
 import { logger } from "../shared/logger.js";
-import { Expiring, RateLimiter } from "./expiring.js";
+import { Expiring, RateLimiter } from "../shared/expiring.js";
 import { PendingLogin } from "./pending-login.js";
 /** Intentos de `/admin/verificar` por cuenta del aula cada 15 minutos: que no sirva para probar contraseñas. */
 const VERIFY_ATTEMPTS = 5;

package/build/oauth/pending-login.d.ts

@@ -0,0 +1,20 @@
+import type { MfaPrompt, SecondFactor } from "../aula-virtual/client/sso-login.js";
+/**
+ * Un login que queda esperando el segundo factor entre un request y otro: corre en segundo plano y,
+ * cuando le pregunta algo al usuario, `next` lo devuelve para mostrárselo en una página; `answer` le
+ * pasa lo que el usuario contestó en el request siguiente.
+ */
+export declare class PendingLogin<T> {
+    private readonly run;
+    private waiting;
+    private listeners;
+    constructor(start: (secondFactor: SecondFactor) => Promise<T>);
+    /** Espera a que el login termine o le pregunte algo al usuario. */
+    next(): Promise<{
+        done: T;
+    } | {
+        prompt: MfaPrompt;
+    }>;
+    /** Contesta lo que está preguntando; si no pregunta nada (un formulario mandado dos veces), no hace nada. */
+    answer(value: string): void;
+}

package/build/oauth/redirects.d.ts

@@ -0,0 +1,20 @@
+/** A dónde puede volver el navegador después del login. */
+export interface RedirectAllowlist {
+    /** Hostnames a los que se vuelve por HTTPS sin aviso. */
+    hosts: Set<string>;
+    /** Esquemas de apps instaladas, con los dos puntos (`cursor:`). */
+    schemes: Set<string>;
+}
+/**
+ * Los conocidos más los de UTN_MCP_REDIRECT_ALLOW, separados por coma: hosts (`app.ejemplo.com`)
+ * o esquemas terminados en dos puntos (`miapp:`).
+ */
+export declare function redirectAllowlistFromEnv(env?: NodeJS.ProcessEnv): RedirectAllowlist;
+/**
+ * `trusted`: loopback, un host HTTPS de la lista o el esquema de una app de la lista.
+ * `unknown`: cualquier otro host HTTPS, como el de un agente propio; se acepta con aviso.
+ * `rejected`: el resto.
+ */
+export declare function redirectTrust(uri: unknown, allow: RedirectAllowlist): "trusted" | "unknown" | "rejected";
+/** Cómo se le nombra al usuario el destino. */
+export declare function describeRedirect(uri: string): string;

package/build/oauth/server.d.ts

@@ -0,0 +1,22 @@
+import { type Express, type RequestHandler } from "express";
+import type { SessionStore } from "../shared/store/session-store.js";
+import type { AccessPolicy } from "./access.js";
+import { type RedirectAllowlist } from "./redirects.js";
+export interface OAuthOptions {
+    /** URL base del servidor, sin barra final: es el issuer y de ahí salen los endpoints. */
+    issuer: string;
+    store: SessionStore;
+    access: AccessPolicy;
+    /** Rechaza los POST de formularios que vengan de otro origen. */
+    sameOrigin: RequestHandler;
+    /** A dónde puede volver el navegador con el code. */
+    redirects: RedirectAllowlist;
+}
+/**
+ * Servidor de autorización OAuth 2.1 para los clientes MCP: registro dinámico, PKCE obligatorio y
+ * clientes públicos. El usuario se identifica con la UTN, y ese mismo login vincula su aula: la
+ * contraseña se usa una vez y no se guarda. Devuelve la URL de la metadata del recurso, que va en el 401.
+ */
+export declare function mountOAuth(app: Express, { issuer, store, access, sameOrigin, redirects }: OAuthOptions): string;
+/** Los endpoints que llaman los clientes desde el navegador (como el MCP Inspector) aceptan cualquier origen. */
+export declare const cors: RequestHandler;

package/build/oauth/server.js

@@ -6,7 +6,7 @@ import { availableRegionals, defaultRegional } from "../aula-virtual/client/regi
 import { InvalidCredentialsError, MfaError } from "../aula-virtual/client/sso-login.js";
 import { logger } from "../shared/logger.js";
 import { escapeHtml, page } from "../shared/pages.js";
-import { Expiring, RateLimiter } from "./expiring.js";
+import { Expiring, RateLimiter } from "../shared/expiring.js";
 import { PendingLogin } from "./pending-login.js";
 import { describeRedirect, redirectTrust } from "./redirects.js";
 /** Duración del access token, en segundos: una baja de acceso se aplica a más tardar en este tiempo. */

package/build/server.d.ts

@@ -0,0 +1,11 @@
+import { McpServer } from "@modelcontextprotocol/server";
+import type { AulaSession } from "./aula-virtual/client/session.js";
+import type { AutogestionAccess } from "./autogestion/client/session.js";
+import type { FileSource } from "./shared/uploads.js";
+/**
+ * Un servidor MCP para un usuario. Las entradas STDIO y HTTP lo crean por conexión o por request.
+ * `files`: de dónde salen los archivos que el usuario sube a una plataforma.
+ * `autogestion`: los conectores cargados y la sesión del usuario; sus tools aparecen solo si uno cubre su regional.
+ * Es async porque resuelve la regional del usuario antes de registrar la autogestión.
+ */
+export declare function createServer(aula: AulaSession, files: FileSource, autogestion?: AutogestionAccess): Promise<McpServer>;

package/build/server.js

@@ -1,14 +1,31 @@
 import { McpServer } from "@modelcontextprotocol/server";
 import { registerAulaVirtualTools } from "./aula-virtual/tools.js";
+import { systemForRegional } from "./autogestion/client/connector.js";
+import { registerAutogestionTools } from "./autogestion/tools.js";
+import { logger } from "./shared/logger.js";
 /**
  * Un servidor MCP para un usuario. Las entradas STDIO y HTTP lo crean por conexión o por request.
  * `files`: de dónde salen los archivos que el usuario sube a una plataforma.
+ * `autogestion`: los conectores cargados y la sesión del usuario; sus tools aparecen solo si uno cubre su regional.
+ * Es async porque resuelve la regional del usuario antes de registrar la autogestión.
  */
-export function createServer(aula, files) {
+export async function createServer(aula, files, autogestion) {
     const server = new McpServer({
         name: "UTN-MCP",
-        version: "0.8.3",
+        version: "0.9.1",
     });
     registerAulaVirtualTools(server, aula, files);
+    if (autogestion?.systems.length) {
+        // Un conector roto no puede dejar sin aula virtual: si falla, seguimos sin las tools de autogestión.
+        try {
+            const regional = await aula.getRegional();
+            const system = systemForRegional(regional.id, autogestion.systems);
+            if (system)
+                registerAutogestionTools(server, autogestion.sessionFor(system, regional.id));
+        }
+        catch (e) {
+            logger.warn(e.message);
+        }
+    }
     return server;
 }

package/build/shared/documents/index.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Lectura de archivos para el modelo: un documento se parte en unidades (páginas, diapositivas,
+ * fragmentos) que se piden de a una, así quien lee decide cuánto entra en una respuesta.
+ */
+export type Part = {
+    title?: string;
+    text: string;
+} | {
+    title?: string;
+    image: Uint8Array;
+    mimeType: string;
+};
+export interface ParsedDocument {
+    format: string;
+    /** Cómo se llama cada parte: "página", "diapositiva", "fragmento"... */
+    unit: string;
+    total: number;
+    /** Numerada desde 1. */
+    part(n: number): Promise<Part>;
+    close(): Promise<void>;
+}
+export declare class UnsupportedFormat extends Error {
+    readonly format: string;
+    constructor(format: string);
+}
+/** Tamaño de cada fragmento cuando un texto largo viene de una sola pieza (un docx, un html). */
+export declare const CHUNK_SIZE = 15000;
+/** Reconoce el formato por los primeros bytes; el nombre solo se usa para los de texto plano. */
+export declare function openDocument(bytes: Uint8Array, name: string): Promise<ParsedDocument>;
+/** Un documento que ya está entero en memoria. */
+export declare function inMemory(format: string, unit: string, parts: Part[]): ParsedDocument;
+/** Corta un texto largo en pedazos de hasta `max` caracteres, prefiriendo cortar en un salto de línea. */
+export declare function splitText(text: string, max?: number): string[];

package/build/shared/documents/merge.d.ts

@@ -0,0 +1,32 @@
+/** Un PDF a unir, con el nombre con que aparece en el índice. */
+export interface MergeInput {
+    title: string;
+    bytes: Uint8Array;
+}
+export interface MergedFile {
+    /** El índice del archivo en la lista de entrada, para reconocerlo después. */
+    index: number;
+    title: string;
+    /** Página del PDF unido en la que empieza, numerada desde 1 (contando el índice). */
+    startPage: number;
+    pages: number;
+}
+export interface SkippedFile {
+    index: number;
+    title: string;
+    reason: string;
+}
+/**
+ * Une PDFs en uno solo, con un índice clickeable al principio: cada entrada abre la página
+ * donde empieza ese material, y cada página de contenido tiene arriba un enlace "Volver al
+ * índice" (en una franja agregada, sin tapar nada). El que no se puede abrir (roto o con
+ * clave) se salta y queda en `skipped`: pdf-lib no desencripta, así que un PDF con clave
+ * entraría con páginas rotas. El índice se arma al final, cuando se sabe qué archivos
+ * entraron, y se inserta al frente.
+ */
+export declare function mergePdfs(files: MergeInput[], documentTitle?: string): Promise<{
+    bytes: Uint8Array;
+    pages: number;
+    merged: MergedFile[];
+    skipped: SkippedFile[];
+}>;

package/build/shared/documents/office.d.ts

@@ -0,0 +1,9 @@
+import { type ParsedDocument } from "./index.js";
+/**
+ * docx, pptx y xlsx son zips de XML. Sacar el texto es leer unos pocos XML; no hace falta
+ * una librería de Office para eso.
+ */
+export type OfficeFormat = "docx" | "pptx" | "xlsx";
+/** Mira la lista de entradas del zip sin descomprimir nada. */
+export declare function detectOfficeFormat(bytes: Uint8Array): OfficeFormat | null;
+export declare function openOffice(bytes: Uint8Array, format: OfficeFormat): ParsedDocument;

package/build/shared/documents/pdf.d.ts

@@ -0,0 +1,2 @@
+import type { ParsedDocument } from "./index.js";
+export declare function openPdf(bytes: Uint8Array): Promise<ParsedDocument>;

package/build/shared/documents/png.d.ts

@@ -0,0 +1,2 @@
+/** PNG en escala de grises, 8 bits. Alcanza para páginas escaneadas y evita una dependencia de imágenes. */
+export declare function grayscalePng(width: number, height: number, pixels: Uint8Array): Uint8Array;

package/build/shared/documents/zip.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Lector mínimo de zip, lo justo para docx/pptx/xlsx: lee el índice (directorio central) del final
+ * del archivo y descomprime las entradas pedidas. Sin zip64 ni cifrado, que Office no usa.
+ */
+export interface ZipEntry {
+    name: string;
+    method: number;
+    compressedSize: number;
+    size: number;
+    /** Dónde empieza el encabezado local de la entrada. */
+    offset: number;
+}
+export declare function listZip(bytes: Uint8Array): ZipEntry[];
+/**
+ * Descomprime una entrada. `max` corta aunque el índice mienta sobre el tamaño: un zip chico que se
+ * infla a gigas es un ataque conocido.
+ */
+export declare function readEntry(bytes: Uint8Array, entry: ZipEntry, max: number): Uint8Array;

package/build/shared/expiring.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Valores que viven en memoria hasta que se usan o vencen, con un id aleatorio que sirve de secreto: los
+ * pedidos de `/authorize` mientras el usuario completa el login, los codes del OAuth hasta que el cliente
+ * los canjea o los links para entrar a la autogestión. Si el servidor se reinicia, se pierden y hay que
+ * volver a empezar, que es lo que pasaría igual con uno vencido.
+ */
+export declare class Expiring<T> {
+    private readonly ttlMs;
+    private readonly items;
+    /** `ttlMs` en milisegundos. */
+    constructor(ttlMs: number);
+    add(value: T): string;
+    get(id: string): T | undefined;
+    /** Lo devuelve y lo borra: un code se canjea una sola vez. */
+    take(id: string): T | undefined;
+    private sweep;
+}
+/** Cuenta intentos por clave (la IP) en una ventana fija. */
+export declare class RateLimiter {
+    private readonly max;
+    private readonly windowMs;
+    private readonly hits;
+    /** `windowMs` en milisegundos. */
+    constructor(max: number, windowMs: number);
+    allow(key: string): boolean;
+}

package/build/{oauth → shared}/expiring.js

@@ -1,8 +1,9 @@
 import { randomBytes } from "node:crypto";
 /**
- * Valores que viven en memoria hasta que se usan o vencen: los pedidos de `/authorize` mientras el
- * usuario completa el login y los codes hasta que el cliente los canjea. Si el servidor se reinicia,
- * se pierden y el cliente vuelve a empezar el OAuth, que es lo que haría igual con un code vencido.
+ * Valores que viven en memoria hasta que se usan o vencen, con un id aleatorio que sirve de secreto: los
+ * pedidos de `/authorize` mientras el usuario completa el login, los codes del OAuth hasta que el cliente
+ * los canjea o los links para entrar a la autogestión. Si el servidor se reinicia, se pierden y hay que
+ * volver a empezar, que es lo que pasaría igual con uno vencido.
  */
 export class Expiring {
     ttlMs;

package/build/shared/html.d.ts

@@ -0,0 +1,6 @@
+/** HTML de Moodle a texto plano: alcanza para que el modelo lo lea, no es un parser. */
+export declare function htmlToText(html: string | undefined): string;
+/** Como htmlToText pero recortado: para índices, donde solo hace falta decidir si entrar. */
+export declare function htmlToSnippet(html: string | undefined, max?: number): string;
+/** Texto plano del modelo a HTML para Moodle: escapa, y cada línea en blanco separa un párrafo. */
+export declare function textToHtml(text: string): string;

package/build/shared/html.js

@@ -1,4 +1,10 @@
-const ENTITIES = { nbsp: " ", amp: "&", lt: "<", gt: ">", quot: '"', apos: "'" };
+// Las con tildes/eñe son las que usan Sysacad y el aula para el español.
+const ENTITIES = {
+    nbsp: " ", amp: "&", lt: "<", gt: ">", quot: '"', apos: "'",
+    aacute: "á", eacute: "é", iacute: "í", oacute: "ó", uacute: "ú", uuml: "ü",
+    Aacute: "Á", Eacute: "É", Iacute: "Í", Oacute: "Ó", Uacute: "Ú", Uuml: "Ü",
+    ntilde: "ñ", Ntilde: "Ñ", iexcl: "¡", iquest: "¿", deg: "°", ordm: "º", ordf: "ª",
+};
 /** HTML de Moodle a texto plano: alcanza para que el modelo lo lea, no es un parser. */
 export function htmlToText(html) {
     if (!html)

package/build/shared/http.d.ts

@@ -0,0 +1,6 @@
+export declare class HttpError extends Error {
+    readonly status?: number | undefined;
+    constructor(message: string, status?: number | undefined);
+}
+/** POST application/x-www-form-urlencoded y parseo JSON, con timeout. */
+export declare function postForm<T>(url: string, params: Record<string, string | number>, timeoutMs?: number): Promise<T>;

package/build/shared/input.d.ts

@@ -0,0 +1,7 @@
+export declare function ask(question: string): Promise<string>;
+/**
+ * Elige una de `options` con las flechas (o su número) y Enter; devuelve el índice. Sin terminal
+ * interactiva (stdin redirigido) muestra la lista numerada y pide el número. Enter solo elige `initial`.
+ */
+export declare function askChoice(question: string, options: string[], initial?: number): Promise<number>;
+export declare function askHidden(question: string): Promise<string>;

package/build/shared/load-env.d.ts

@@ -0,0 +1 @@
+export {};