utn-mcp 0.8.2 → 0.9.0

package/build/aula-virtual/format/study-pack.js

@@ -0,0 +1,199 @@
+import { createHash } from "node:crypto";
+import { mkdir, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { mergePdfs } from "../../shared/documents/merge.js";
+import { exportsDir } from "../../shared/paths.js";
+import { getCourseFiles, getUserCourses } from "../client/client.js";
+import { parseAddress } from "./address.js";
+import { downloadUrl, MAX_BYTES } from "./files.js";
+import { fetchFile } from "../client/moodle-api.js";
+/**
+ * Topes de tamaño por pack: pdf-lib junta todo el resultado en memoria, así que sin tope total un
+ * curso enorme podría colgar la compu donde corre el servidor. Lo que queda afuera por un tope se
+ * lista en `omitidos` con el motivo, para pedir el resto en otro pack.
+ * Una variable de entorno con basura NO puede desactivar el tope: si no es un número válido,
+ * vuelve al default.
+ */
+const capFromEnv = (raw, fallback) => {
+    const n = Number(raw ?? fallback);
+    return Number.isFinite(n) && n > 0 ? n : fallback;
+};
+const MAX_PACK_FILES = capFromEnv(process.env.UTN_MCP_PACK_MAX_FILES, 150);
+const MAX_PACK_BYTES = capFromEnv(process.env.UTN_MCP_PACK_MAX_MB, 300) * 1024 * 1024;
+/** Máximo del PDF final: se estima con los tamaños de entrada para cortar antes de bajar todo. */
+const MAX_FINAL_MB = capFromEnv(process.env.UTN_MCP_PACK_MAX_FINAL_MB, 30);
+const MAX_FINAL_BYTES = MAX_FINAL_MB * 1024 * 1024;
+const isPdf = (e) => e.file.mimetype === "application/pdf" || e.file.filename.toLowerCase().endsWith(".pdf");
+/** Los caracteres que no sirven para un nombre de archivo se cambian por "-". */
+const safeFileName = (name) => name.replace(/[^\p{L}\p{N}._-]+/gu, "-").replace(/^-+|-+$/g, "");
+/**
+ * Escribe el pack sin pisar packs anteriores: nombre con fecha-hora y, si ya existe (dos packs
+ * en el mismo segundo), un sufijo -2, -3... La escritura es atómica por nombre (bandera "wx").
+ */
+export async function writePackFile(dir, courseName, bytes) {
+    const now = new Date();
+    const pad = (n) => String(n).padStart(2, "0");
+    const stamp = `${now.getFullYear()}${pad(now.getMonth() + 1)}${pad(now.getDate())}-${pad(now.getHours())}${pad(now.getMinutes())}${pad(now.getSeconds())}`;
+    const base = join(dir, `${safeFileName(courseName)}-apuntes-${stamp}`);
+    for (let n = 1; n <= 100; n++) {
+        const candidate = n === 1 ? `${base}.pdf` : `${base}-${n}.pdf`;
+        try {
+            await writeFile(candidate, bytes, { flag: "wx" });
+            return candidate;
+        }
+        catch (e) {
+            if (e.code !== "EEXIST")
+                throw e;
+        }
+    }
+    throw new Error(`No se pudo guardar el pack: ya existen 100 archivos para "${base}".`);
+}
+/**
+ * Baja PDF de un curso y los une en un solo archivo con índice, guardado en exportsDir().
+ * Con `archivos` une solo las URL pedidas (tal como las devuelve aula_open, validadas con
+ * `downloadUrl` como en aula_read_file); sin `archivos`, todos los PDF del curso. El pack sigue
+ * el orden del aula, no el de la lista, para que el índice acompañe las unidades. Los duplicados
+ * exactos se descartan al armar, porque ahí se bajan igual. Todo lo omitido queda listado en
+ * `omitidos` con el motivo; en el atajo sin `archivos`, los archivos que no son PDF solo se
+ * cuentan en `archivosNoPdf` en vez de listarse uno por uno.
+ */
+export async function buildStudyPack(session, rawAddress, archivos) {
+    const address = parseAddress(rawAddress);
+    if (address.level !== "course") {
+        throw new Error(`Para armar el pack pasá la dirección de un curso entero ("/curso/{courseId}", de aula_list_courses), no "${rawAddress}".`);
+    }
+    const { baseUrl } = await session.getRegional();
+    const course = (await getUserCourses(session)).find((c) => c.id === address.courseId);
+    const entries = await getCourseFiles(session, address.courseId);
+    let selected;
+    const omitted = [];
+    if (archivos) {
+        // Cada URL pedida se valida igual que en aula_read_file: solo archivos del aula del usuario.
+        const requested = new Set(archivos.map((u) => downloadUrl(baseUrl, u).href));
+        const byUrl = new Map(entries.map((e) => [downloadUrl(baseUrl, e.file.fileurl).href, e]));
+        const unknown = [...requested].filter((u) => !byUrl.has(u));
+        if (unknown.length) {
+            throw new Error(`Estas URL no son de archivos del curso (salen de aula_open sobre "${rawAddress}"):\n` +
+                unknown.map((u) => `- ${u}`).join("\n"));
+        }
+        // El orden lo manda el aula, no la lista: el índice sigue las unidades.
+        selected = entries.filter((e) => requested.has(downloadUrl(baseUrl, e.file.fileurl).href));
+        for (const e of selected.filter((x) => !isPdf(x))) {
+            omitted.push({ nombre: e.file.filename, seccion: e.section, motivo: "no es un PDF" });
+        }
+    }
+    else {
+        selected = entries;
+    }
+    const pdfs = selected.filter(isPdf);
+    const archivosNoPdf = archivos ? 0 : selected.length - pdfs.length;
+    if (!pdfs.length) {
+        throw new Error(archivos
+            ? "Ninguna de las URL pedidas es un PDF: la tool une únicamente PDF."
+            : "El curso no tiene ningún PDF en sus secciones visibles.");
+    }
+    const capMotivo = `se alcanzó el tope del pack (${MAX_PACK_FILES} archivos / ${MAX_PACK_BYTES / 1024 / 1024} MB)`;
+    const inputs = [];
+    const kept = [];
+    const seen = new Map(); // hash -> nombre del primero con ese contenido
+    let totalBytes = 0;
+    let finalLleno = false;
+    for (const entry of pdfs) {
+        const name = entry.file.filename;
+        if (finalLleno) {
+            omitted.push({
+                nombre: name,
+                seccion: entry.section,
+                motivo: `el PDF final llegó al tope de ${MAX_FINAL_MB} MB (estimado con los tamaños de entrada)`,
+            });
+            continue;
+        }
+        if (inputs.length >= MAX_PACK_FILES || totalBytes + (entry.file.filesize ?? 0) > MAX_PACK_BYTES) {
+            omitted.push({ nombre: name, seccion: entry.section, motivo: capMotivo });
+            continue;
+        }
+        let bytes;
+        try {
+            bytes = (await fetchFile(session, downloadUrl(baseUrl, entry.file.fileurl), MAX_BYTES)).bytes;
+        }
+        catch (e) {
+            omitted.push({ nombre: name, seccion: entry.section, motivo: e.message });
+            continue;
+        }
+        const hash = createHash("sha256").update(bytes).digest("hex");
+        const original = seen.get(hash);
+        if (original) {
+            omitted.push({ nombre: name, seccion: entry.section, motivo: `es idéntico a "${original}"` });
+            continue;
+        }
+        // El tamaño real se conoce recién ahora (Moodle a veces no lo anuncia): tope post-descarga.
+        if (totalBytes + bytes.length > MAX_PACK_BYTES) {
+            omitted.push({ nombre: name, seccion: entry.section, motivo: capMotivo });
+            continue;
+        }
+        // Corte temprano del tope del PDF final, estimado con los tamaños de entrada: lo que ya
+        // no puede entrar no se baja de más ni tira abajo el pack entero al final.
+        if (totalBytes + bytes.length > MAX_FINAL_BYTES) {
+            finalLleno = true;
+            omitted.push({
+                nombre: name,
+                seccion: entry.section,
+                motivo: `el PDF final llegó al tope de ${MAX_FINAL_MB} MB (estimado con los tamaños de entrada)`,
+            });
+            continue;
+        }
+        seen.set(hash, name);
+        inputs.push({ title: name, bytes });
+        kept.push(entry);
+        totalBytes += bytes.length;
+    }
+    // En el índice va el módulo, que se lee mejor que el archivo; si el módulo aporta más de un
+    // archivo, también el archivo, para que las entradas no queden repetidas.
+    const perModule = new Map();
+    const moduleKey = (e) => `${e.section}\n${e.module}`;
+    for (const e of kept)
+        perModule.set(moduleKey(e), (perModule.get(moduleKey(e)) ?? 0) + 1);
+    kept.forEach((e, i) => {
+        inputs[i].title = perModule.get(moduleKey(e)) > 1 ? `${e.module}: ${e.file.filename}` : e.module;
+    });
+    const courseName = course?.shortname ?? `curso-${address.courseId}`;
+    const dir = exportsDir();
+    // La estimación puede quedar corta (el índice y los enlaces agregan páginas): si el unido
+    // supera el tope igual, salen los últimos materiales hasta que entre, en vez de tirar todo
+    // el trabajo de descarga.
+    let pack = await mergePdfs(inputs, `Apuntes de ${course?.fullname ?? courseName}`);
+    while (pack.bytes.length > MAX_FINAL_BYTES && inputs.length > 1) {
+        inputs.pop();
+        const entry = kept.pop();
+        omitted.push({
+            nombre: entry.file.filename,
+            seccion: entry.section,
+            motivo: `el PDF final superó el tope de ${MAX_FINAL_MB} MB al unir`,
+        });
+        pack = await mergePdfs(inputs, `Apuntes de ${course?.fullname ?? courseName}`);
+    }
+    if (pack.bytes.length > MAX_FINAL_BYTES) {
+        const mb = Math.round((pack.bytes.length / 1024 / 1024) * 10) / 10;
+        throw new Error(`El PDF final pesa ${mb} MB, más del máximo (${MAX_FINAL_MB} MB): no se guardó. ` +
+            "Pedí el pack con `archivos`, eligiendo solo los PDF que necesitás.");
+    }
+    for (const s of pack.skipped) {
+        omitted.push({ nombre: kept[s.index].file.filename, seccion: kept[s.index].section, motivo: s.reason });
+    }
+    await mkdir(dir, { recursive: true });
+    const path = await writePackFile(dir, courseName, pack.bytes);
+    return {
+        archivo: path,
+        curso: course?.fullname ?? courseName,
+        paginas: pack.pages,
+        materiales: pack.merged.map((m) => ({
+            nombre: kept[m.index].file.filename,
+            seccion: kept[m.index].section,
+            modulo: kept[m.index].module,
+            paginas: m.pages,
+            empiezaEn: m.startPage,
+        })),
+        omitidos: omitted.length ? omitted : undefined,
+        archivosNoPdf: archivosNoPdf || undefined,
+    };
+}

package/build/aula-virtual/format/submission.d.ts

@@ -0,0 +1,40 @@
+import { type FileSource, type UploadInbox } from "../../shared/uploads.js";
+import type { AulaSession } from "../client/session.js";
+export interface SubmissionRequest {
+    /** La lista final de archivos: rutas locales (solo STDIO) o la `url` de uno que ya está en la entrega. */
+    files?: string[];
+    /** Id de un link de subida (solo HTTP): sus archivos se suman a la lista. */
+    upload?: string;
+    /** Texto plano del modelo; reemplaza el texto en línea. */
+    text?: string;
+    /** Confirmar el envío si la tarea usa borradores. */
+    send: boolean;
+    acceptStatement: boolean;
+}
+/** Abre un link para recibir los archivos de una entrega en modo HTTP, con los límites de la tarea. */
+export declare function createUploadLink(session: AulaSession, rawAddress: string, inbox: UploadInbox, owner: string): Promise<{
+    subida: string;
+    url: string;
+    vence: string;
+    acepta: {
+        maximo: number | undefined;
+        tamanioMaximo: number;
+        extensiones: string | undefined;
+    };
+    conTerminal: string;
+}>;
+/**
+ * Deja la entrega con los archivos y el texto pedidos, y la envía si hace falta. Lo que no se pasa
+ * se conserva: Moodle reemplaza cada plugin con lo que recibe, así que se le reenvía lo que ya tenía.
+ */
+export declare function submitAssignment(session: AulaSession, rawAddress: string, request: SubmissionRequest, source: FileSource): Promise<{
+    direccion: string;
+    estado: string;
+    aviso: string | undefined;
+    archivos: {
+        nombre: string;
+        tamanio: number;
+        url: string;
+    }[] | undefined;
+    texto: string | undefined;
+}>;

package/build/aula-virtual/login.d.ts

@@ -0,0 +1,6 @@
+/**
+ * `utn-mcp login`: pide la regional, usuario y contraseña una vez, los guarda en el keychain
+ * y obtiene el primer token. Después el servidor renueva solo.
+ * Con `--http` guarda la sesión en el store y emite el token para el cliente MCP.
+ */
+export declare function runLogin(http: boolean): Promise<void>;

package/build/aula-virtual/tools.d.ts

@@ -0,0 +1,4 @@
+import type { McpServer } from "@modelcontextprotocol/server";
+import type { FileSource } from "../shared/uploads.js";
+import type { AulaSession } from "./client/session.js";
+export declare function registerAulaVirtualTools(server: McpServer, session: AulaSession, files: FileSource): void;

package/build/aula-virtual/tools.js

@@ -3,6 +3,7 @@ import { getSiteInfo } from "./client/client.js";
 import { addCalendarEvent, answerChoice, deleteForumPost, editForumPost, postToForum, sendMessage, } from "./format/actions.js";
 import { ROOT } from "./format/address.js";
 import { readAulaFile } from "./format/files.js";
+import { buildStudyPack } from "./format/study-pack.js";
 import { open } from "./format/navigate.js";
 import { createUploadLink, submitAssignment } from "./format/submission.js";
 // JSON compacto: indentar estas respuestas cuesta ~25% más de contexto y no se lee mejor.
@@ -125,6 +126,45 @@ export function registerAulaVirtualTools(server, session, files) {
             return failure(e);
         }
     });
+    // El pack se guarda en el disco: solo en STDIO, donde el servidor corre en la compu del usuario.
+    if (files.local) {
+        server.registerTool("aula_study_pack", {
+            description: "Une PDF del aula en un solo compilado de estudio con índice clickeable (cada " +
+                "entrada abre la página donde empieza ese material, y cada página tiene arriba " +
+                "un enlace para volver), guardado en la compu del usuario. Une ÚNICAMENTE PDF; " +
+                "si una URL pedida no es PDF, queda en `omitidos` con el motivo.\n\n" +
+                "Conviene llamar antes a aula_open del curso: devuelve cada módulo con sus " +
+                "archivos (nombre, url, sección y tipo) y permite elegir los apuntes sin bajar " +
+                "nada. Es un compilado íntegro, no un resumen.\n\n" +
+                "Hay topes por memoria: 150 archivos, 300 MB de descarga total y 30 MB el PDF " +
+                "final (estimado con los tamaños de entrada, para no bajar archivos de más). Lo " +
+                "que no entra queda en `omitidos` con el motivo: se pide el resto en otro pack. " +
+                "La respuesta trae la ruta en `archivo` y `materiales` con sección, módulo, " +
+                "páginas y página de inicio de cada uno.\n\n" +
+                "La `direccion` del curso sale de aula_list_courses. Para leer o pasarle al " +
+                "usuario archivos que no son PDF, usá aula_open y aula_read_file.",
+            inputSchema: z.object({
+                direccion: z
+                    .string()
+                    .describe('Dirección del curso, de aula_list_courses. Ej: "/curso/691".'),
+                archivos: z
+                    .array(z.string())
+                    .optional()
+                    .describe("URL de los PDF a unir, tal como las devuelve aula_open del curso (conviene " +
+                    "llamarlo antes y elegir: cada archivo trae nombre, sección y tipo). El pack " +
+                    "sigue el orden del aula, no el de esta lista. Sin `archivos`, une todos los " +
+                    "PDF del curso."),
+            }),
+            annotations: { readOnlyHint: false, destructiveHint: false, openWorldHint: false },
+        }, async ({ direccion, archivos }) => {
+            try {
+                return json(await buildStudyPack(session, direccion, archivos));
+            }
+            catch (e) {
+                return failure(e);
+            }
+        });
+    }
     // --- Escritura: lo que sigue cambia algo en el aula, y casi todo queda a la vista de otras personas. ---
     const CONFIRM_FIRST = "\n\nAntes de llamarla, mostrale al usuario exactamente lo que se va a hacer y esperá que confirme.";
     server.registerTool("aula_forum_post", {

package/build/autogestion/client/catalog.d.ts

@@ -0,0 +1,20 @@
+/** Qué se sabe del conector en una regional: `verified` = alguien entró con una cuenta real; `candidate` = falta esa prueba. */
+export type SystemSupport = "verified" | "candidate";
+/**
+ * Un conector que `utn-mcp login` sabe instalar: el `.tgz` de `npm pack` adjunto a un release del repo.
+ * La URL fija la versión y `integrity` el contenido exacto: cargar un paquete es ejecutar su código,
+ * así que solo se instala lo que nombra este catálogo, nunca un nombre que venga del usuario o del entorno.
+ */
+export interface CatalogEntry {
+    id: string;
+    name: string;
+    package: string;
+    version: string;
+    tarball: string;
+    /** sha512 del `.tgz` en base64, como el campo `integrity` de npm. */
+    integrity: string;
+    /** Las regionales que atiende y su soporte, para ofrecerlo en el login antes de bajar nada. */
+    regionales: Record<string, SystemSupport>;
+}
+export declare const CATALOG: CatalogEntry[];
+export declare function catalogEntryForRegional(regionalId: string): CatalogEntry | null;

package/build/autogestion/client/catalog.js

@@ -0,0 +1,22 @@
+const RELEASES = "https://github.com/nialvape/utn-mcp/releases/download";
+/** Las mismas regionales que `ASP_REGIONALS` del paquete; las que quedaron afuera dicen por qué ahí. */
+const SYSACAD_ASP_REGIONALS = [
+    "frbb", "frch", "frcon", "frd", "frgp", "frh", "frlr", "frmdp", "frn",
+    "frp", "frrq", "frsf", "frsfco", "frsn", "frsr", "frt", "frtdf", "frvt",
+];
+export const CATALOG = [
+    {
+        id: "sysacad-asp",
+        name: "Sysacad",
+        package: "utn-mcp-sysacad-asp",
+        version: "0.1.0",
+        tarball: `${RELEASES}/sysacad-asp-v0.1.0/utn-mcp-sysacad-asp-0.1.0.tgz`,
+        integrity: "sha512-dFiMVUwQJdLHmrKD6BZnUgn5EU73pzAzSBEEQyCA4P2eXOI6QeTRLnmGW//K1hmFJXl74Ax10VQrpVweY6+1Gw==",
+        // FRT anduvo con cuenta real (oct 2026) con la versión anterior, que posteaba directo a `menuAlumno.asp`;
+        // esta lee el formulario y todavía no entró nadie con ella.
+        regionales: Object.fromEntries(SYSACAD_ASP_REGIONALS.map((id) => [id, "candidate"])),
+    },
+];
+export function catalogEntryForRegional(regionalId) {
+    return CATALOG.find((entry) => regionalId in entry.regionales) ?? null;
+}

package/build/autogestion/client/connector.d.ts

@@ -0,0 +1,61 @@
+import { HttpError } from "../../shared/http.js";
+import { htmlToText } from "../../shared/html.js";
+import type { Correlatividades, EstadoMateria, ExamenMateria, NotasParcialesMateria } from "./types.js";
+/**
+ * Un sistema de autogestión académica (Sysacad, SIU Guaraní, etc.) logueado con un usuario.
+ * Cada sistema es un paquete aparte que exporta un `AutogestionSystem`; el core lo instala desde su
+ * catálogo y le pide un conector para la regional del usuario.
+ */
+export interface AutogestionConnector {
+    /** Id del sistema, tal como lo declara el paquete que lo provee. */
+    readonly systemId: string;
+    /** Pide legajo/usuario y contraseña al sistema y deja la sesión lista. */
+    login(credentials: AutogestionCredentials): Promise<void>;
+    /** Materias del estado académico del alumno logueado, ya parseadas. */
+    estadoAcademico(): Promise<EstadoMateria[]>;
+    /** Correlatividades de la carrera del alumno logueado, para cursar y, si el sistema las publica, para rendir. */
+    correlatividades(): Promise<Correlatividades>;
+    /** Cursada actual, si el sistema la publica; no todos los conectores la tienen. */
+    notasParciales?(): Promise<NotasParcialesMateria[]>;
+    /** Historial de exámenes finales, si el sistema lo publica; no todos los conectores lo tienen. */
+    examenes?(): Promise<ExamenMateria[]>;
+}
+/** Credenciales de un sistema de autogestión. En Sysacad `username` es el legajo. */
+export interface AutogestionCredentials {
+    username: string;
+    password: string;
+}
+export declare class LoginRequiredError extends Error {
+    constructor(systemName: string);
+}
+export declare class InvalidCredentialsError extends Error {
+    constructor(systemName: string);
+}
+export declare class UnsupportedRegionalError extends Error {
+    constructor(regionalId: string);
+}
+/**
+ * Lo que el core le presta al conector en `create`. El paquete importa del core solo tipos: instalado
+ * en otra carpeta, un import en tiempo de ejecución cargaría otra copia de `utn-mcp`, con otras clases
+ * de error que el core no reconoce.
+ */
+export declare const connectorKit: {
+    HttpError: typeof HttpError;
+    LoginRequiredError: typeof LoginRequiredError;
+    InvalidCredentialsError: typeof InvalidCredentialsError;
+    htmlToText: typeof htmlToText;
+};
+export type ConnectorKit = typeof connectorKit;
+/** Lo que exporta un paquete de conector: qué regionales atiende y cómo crear el conector de cada una. */
+export interface AutogestionSystem {
+    id: string;
+    name: string;
+    /** Ids de regional como en `regionals.ts` del aula (`frt`, `frd`...). */
+    regionales: string[];
+    /** Ayuda para el usuario de esa regional, si no es el legajo tal cual: "Legajo sin el 23-". */
+    usernameHint?(regionalId: string): string | undefined;
+    create(regionalId: string, kit: ConnectorKit): AutogestionConnector;
+}
+/** El sistema de una regional entre los conectores cargados, o null si ninguno la cubre. */
+export declare function systemForRegional(regionalId: string, systems: AutogestionSystem[]): AutogestionSystem | null;
+export type { CorrelatividadMateria, Correlatividades, EstadoMateria, ExamenMateria, NotasParcialesMateria } from "./types.js";

package/build/autogestion/client/connector.js

@@ -0,0 +1,31 @@
+import { HttpError } from "../../shared/http.js";
+import { htmlToText } from "../../shared/html.js";
+export class LoginRequiredError extends Error {
+    constructor(systemName) {
+        super(`Falta iniciar sesión en ${systemName}: corré \`utn-mcp login autogestion\` una vez.`);
+        this.name = "LoginRequiredError";
+    }
+}
+export class InvalidCredentialsError extends Error {
+    constructor(systemName) {
+        super(`${systemName} rechazó el usuario o la contraseña. Revisalos con \`utn-mcp login autogestion\`.`);
+        this.name = "InvalidCredentialsError";
+    }
+}
+export class UnsupportedRegionalError extends Error {
+    constructor(regionalId) {
+        super(`La regional ${regionalId.toUpperCase()} todavía no tiene un conector de autogestión. ` +
+            "El aula virtual se puede seguir usando sin autogestión.");
+        this.name = "UnsupportedRegionalError";
+    }
+}
+/**
+ * Lo que el core le presta al conector en `create`. El paquete importa del core solo tipos: instalado
+ * en otra carpeta, un import en tiempo de ejecución cargaría otra copia de `utn-mcp`, con otras clases
+ * de error que el core no reconoce.
+ */
+export const connectorKit = { HttpError, LoginRequiredError, InvalidCredentialsError, htmlToText };
+/** El sistema de una regional entre los conectores cargados, o null si ninguno la cubre. */
+export function systemForRegional(regionalId, systems) {
+    return systems.find((system) => system.regionales.includes(regionalId)) ?? null;
+}

package/build/autogestion/client/credentials.d.ts

@@ -0,0 +1,5 @@
+import type { AutogestionCredentials } from "./connector.js";
+/** Primero <SISTEMA>_USER/<SISTEMA>_PASS (ej. SYSACAD_ASP_USER); si no están, el keychain. */
+export declare function loadAutogestionCredentials(systemId: string): Promise<AutogestionCredentials | null>;
+/** Guarda en el keychain. Devuelve false si no hay keychain (ej. Linux sin Secret Service). */
+export declare function saveAutogestionCredentials(systemId: string, creds: AutogestionCredentials): Promise<boolean>;

package/build/autogestion/client/credentials.js

@@ -0,0 +1,40 @@
+import { logger } from "../../shared/logger.js";
+const SERVICE = "utn-mcp";
+/** Una entrada por sistema: la credencial es por sistema, no por regional. */
+const account = (systemId) => `autogestion-${systemId}`;
+// Import dinámico: si el binario nativo o el Secret Service (Linux) no están, seguimos con env vars.
+async function entry(systemId) {
+    const { Entry } = await import("@napi-rs/keyring");
+    return new Entry(SERVICE, account(systemId));
+}
+function envNames(systemId) {
+    const prefix = systemId.toUpperCase().replace(/[^A-Z0-9]/g, "_");
+    return [`${prefix}_USER`, `${prefix}_PASS`];
+}
+/** Primero <SISTEMA>_USER/<SISTEMA>_PASS (ej. SYSACAD_ASP_USER); si no están, el keychain. */
+export async function loadAutogestionCredentials(systemId) {
+    const [userEnv, passEnv] = envNames(systemId);
+    const username = process.env[userEnv];
+    const password = process.env[passEnv];
+    if (username && password)
+        return { username, password };
+    try {
+        const raw = (await entry(systemId)).getPassword();
+        return raw ? JSON.parse(raw) : null;
+    }
+    catch (e) {
+        logger.warn("Keychain no disponible:", e.message);
+        return null;
+    }
+}
+/** Guarda en el keychain. Devuelve false si no hay keychain (ej. Linux sin Secret Service). */
+export async function saveAutogestionCredentials(systemId, creds) {
+    try {
+        (await entry(systemId)).setPassword(JSON.stringify(creds));
+        return true;
+    }
+    catch (e) {
+        logger.warn("No se pudo guardar en el keychain:", e.message);
+        return false;
+    }
+}

package/build/autogestion/client/install.d.ts

@@ -0,0 +1,14 @@
+import type { CatalogEntry } from "./catalog.js";
+/** Donde quedan los conectores instalados, uno por carpeta con el nombre de su paquete. */
+export declare const connectorsDir: () => string;
+export declare const connectorDir: (entry: CatalogEntry) => string;
+/** El package.json del conector instalado, o null si no está. */
+export declare function installedManifest(entry: CatalogEntry): Promise<{
+    version?: string;
+    main?: string;
+} | null>;
+/**
+ * Baja el `.tgz` del catálogo, comprueba su hash y lo extrae en su carpeta. Sin `npm install`: los
+ * conectores no tienen dependencias, así que alcanza con desempaquetarlos, y no hace falta npm en la máquina.
+ */
+export declare function installConnector(entry: CatalogEntry): Promise<void>;

package/build/autogestion/client/install.js

@@ -0,0 +1,72 @@
+import { createHash } from "node:crypto";
+import { mkdir, readFile, rename, rm, writeFile } from "node:fs/promises";
+import { dirname, isAbsolute, join } from "node:path";
+import { gunzipSync } from "node:zlib";
+import { HttpError } from "../../shared/http.js";
+import { configDir } from "../../shared/paths.js";
+/** Donde quedan los conectores instalados, uno por carpeta con el nombre de su paquete. */
+export const connectorsDir = () => join(configDir(), "connectors");
+export const connectorDir = (entry) => join(connectorsDir(), entry.package);
+/** El package.json del conector instalado, o null si no está. */
+export async function installedManifest(entry) {
+    try {
+        return JSON.parse(await readFile(join(connectorDir(entry), "package.json"), "utf8"));
+    }
+    catch {
+        return null;
+    }
+}
+/** Bloques del formato tar: encabezado y datos van de a 512 bytes. */
+const TAR_BLOCK = 512;
+/**
+ * Baja el `.tgz` del catálogo, comprueba su hash y lo extrae en su carpeta. Sin `npm install`: los
+ * conectores no tienen dependencias, así que alcanza con desempaquetarlos, y no hace falta npm en la máquina.
+ */
+export async function installConnector(entry) {
+    let res;
+    try {
+        res = await fetch(entry.tarball, { signal: AbortSignal.timeout(60_000) });
+    }
+    catch (e) {
+        throw new HttpError(`No se pudo bajar el conector de ${entry.name}: ${e.message}`);
+    }
+    if (!res.ok)
+        throw new HttpError(`HTTP ${res.status} al bajar el conector de ${entry.name} (${entry.tarball}).`, res.status);
+    const tgz = Buffer.from(await res.arrayBuffer());
+    const integrity = `sha512-${createHash("sha512").update(tgz).digest("base64")}`;
+    if (integrity !== entry.integrity) {
+        throw new Error(`El conector de ${entry.name} que se bajó no es el que espera esta versión de utn-mcp: no se instala.`);
+    }
+    const target = connectorDir(entry);
+    const staging = `${target}.tmp-${process.pid}`;
+    await rm(staging, { recursive: true, force: true });
+    await extractPackage(tgz, staging);
+    await rm(target, { recursive: true, force: true });
+    await rename(staging, target);
+}
+/** Extrae los archivos de `package/` de un tarball de `npm pack`; cualquier ruta que salga de ahí se rechaza. */
+async function extractPackage(tgz, dest) {
+    const tar = gunzipSync(tgz);
+    const text = (start, length) => tar.subarray(start, start + length).toString("utf8").replace(/\0.*$/s, "");
+    for (let offset = 0; offset + TAR_BLOCK <= tar.length;) {
+        if (tar.subarray(offset, offset + TAR_BLOCK).every((b) => b === 0))
+            break;
+        const name = text(offset, 100);
+        const prefix = text(offset + 345, 155);
+        const size = parseInt(text(offset + 124, 12).trim() || "0", 8);
+        // "0" o NUL es un archivo común; los demás (carpetas, encabezados pax) no traen nada que escribir.
+        const type = String.fromCharCode(tar[offset + 156]);
+        const path = prefix ? `${prefix}/${name}` : name;
+        const data = offset + TAR_BLOCK;
+        if (type === "0" || type === "\0") {
+            const relative = path.replace(/^package\//, "");
+            if (!path.startsWith("package/") || isAbsolute(relative) || relative.split(/[\\/]/).includes("..")) {
+                throw new Error(`El conector trae una ruta inválida (${path}): no se instala.`);
+            }
+            const file = join(dest, relative);
+            await mkdir(dirname(file), { recursive: true });
+            await writeFile(file, tar.subarray(data, data + size));
+        }
+        offset = data + Math.ceil(size / TAR_BLOCK) * TAR_BLOCK;
+    }
+}

package/build/autogestion/client/installed-systems.d.ts

@@ -0,0 +1,7 @@
+import type { AutogestionSystem } from "./connector.js";
+/**
+ * Los conectores disponibles: los del catálogo que `utn-mcp login` instaló en la carpeta de datos y,
+ * a mano, los paquetes que nombre `UTN_MCP_CONNECTORS`, resueltos desde la carpeta en la que arranca
+ * el proceso. Esa variable es para probar un conector propio: cargarlo ejecuta su código.
+ */
+export declare function loadInstalledSystems(): Promise<AutogestionSystem[]>;

package/build/autogestion/client/installed-systems.js

@@ -0,0 +1,58 @@
+import { createRequire } from "node:module";
+import { join } from "node:path";
+import { pathToFileURL } from "node:url";
+import { logger } from "../../shared/logger.js";
+import { CATALOG } from "./catalog.js";
+import { connectorDir, installedManifest } from "./install.js";
+/**
+ * Los conectores disponibles: los del catálogo que `utn-mcp login` instaló en la carpeta de datos y,
+ * a mano, los paquetes que nombre `UTN_MCP_CONNECTORS`, resueltos desde la carpeta en la que arranca
+ * el proceso. Esa variable es para probar un conector propio: cargarlo ejecuta su código.
+ */
+export async function loadInstalledSystems() {
+    const systems = [];
+    for (const entry of CATALOG) {
+        const system = await loadFromCatalog(entry);
+        if (system)
+            systems.push(system);
+    }
+    const manual = process.env.UTN_MCP_CONNECTORS?.split(",").map((name) => name.trim()).filter(Boolean) ?? [];
+    const require = createRequire(join(process.cwd(), "package.json"));
+    for (const name of new Set(manual)) {
+        const system = validSystem(await import(pathToFileURL(require.resolve(name)).href), name);
+        if (systems.some((existing) => existing.id === system.id || existing.regionales.some((id) => system.regionales.includes(id)))) {
+            throw new Error(`El conector ${name} repite un sistema o una regional que ya cubre otro conector.`);
+        }
+        systems.push(system);
+    }
+    return systems;
+}
+/** El conector del catálogo si está instalado y es la versión que espera este core; si no, null. */
+async function loadFromCatalog(entry) {
+    const manifest = await installedManifest(entry);
+    if (!manifest)
+        return null;
+    if (manifest.version !== entry.version) {
+        logger.warn(`El conector de ${entry.name} instalado es la versión ${manifest.version} y esta versión de utn-mcp usa la ` +
+            `${entry.version}: corré \`utn-mcp login autogestion\` para actualizarlo.`);
+        return null;
+    }
+    const system = validSystem(await import(pathToFileURL(join(connectorDir(entry), manifest.main ?? "index.js")).href), entry.package);
+    if (system.id !== entry.id)
+        throw new Error(`El paquete ${entry.package} no es el conector ${entry.id}.`);
+    return system;
+}
+function validSystem(module, source) {
+    const system = module.default;
+    const nonEmpty = (value) => typeof value === "string" && value.trim() !== "";
+    if (!system ||
+        !nonEmpty(system.id) ||
+        !nonEmpty(system.name) ||
+        !Array.isArray(system.regionales) ||
+        system.regionales.length === 0 ||
+        !system.regionales.every(nonEmpty) ||
+        typeof system.create !== "function") {
+        throw new Error(`El paquete ${source} no exporta un conector de autogestión válido.`);
+    }
+    return system;
+}