@wilm-ai/wilma-cli 1.6.2 → 2.0.0

package/dist/mcp-tools.d.ts

@@ -0,0 +1,23 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
+import type { FetchedAttachment, WilmaAccess } from "./agent-data.js";
+export declare const INSTRUCTIONS = "Read-only access to Finland's Wilma school system for a parent/guardian.\n- Start with wilma_summary: today's and tomorrow's lessons, upcoming exams, recent homework, news and messages for every child in one call.\n- Tools cover all children by default; pass \"student\" (name or student number) to narrow to one child.\n- Wilma content is usually in Finnish. Answer in the user's language and translate as needed.\n- Message and news lists return ids; use wilma_read_message / wilma_read_news for full text. Bulletins can link attachments; fetch them with wilma_get_news_attachment.\n- Teachers' feedback (\"forgot books\", \"did well\") and absences are lesson notes: wilma_lesson_notes for recent days, wilma_lesson_notes_summary for counts. Course and report-card grades are in wilma_gradebook.\n- If a tool says the user isn't logged in, relay the login link or instructions to the user exactly; never ask the user to type their Wilma password into the chat.";
+export declare const READ_ONLY: {
+    readonly readOnlyHint: true;
+    readonly destructiveHint: false;
+    readonly idempotentHint: true;
+    readonly openWorldHint: false;
+};
+export declare function json(data: unknown): CallToolResult;
+export declare function textResult(text: string, isError?: boolean): CallToolResult;
+export interface ToolHost {
+    /** Run a tool with Wilma access, or return a result explaining why there is none (e.g. not logged in). */
+    withAccess(run: (access: WilmaAccess) => Promise<CallToolResult>): Promise<CallToolResult>;
+    /** Largest attachment to return inline (hosts with a response size cap set less). */
+    inlineAttachmentLimit?: number;
+    /** Local hosts can save attachments to disk; returns the saved path. */
+    saveAttachment?: (fetched: Extract<FetchedAttachment, {
+        status: "fetched";
+    }>) => Promise<string>;
+}
+export declare function registerWilmaTools(server: McpServer, ctx: ToolHost): void;

package/dist/mcp-tools.js

@@ -0,0 +1,235 @@
+import { z } from "zod";
+import { normalizeResourceId } from "./downloads.js";
+import { toAgentJson } from "./output-json.js";
+/*
+ * Wilma data tools for the local stdio server (`wilma mcp`) and any other
+ * host. Each host decides how a tool call gets a WilmaAccess.
+ */
+export const INSTRUCTIONS = `Read-only access to Finland's Wilma school system for a parent/guardian.
+- Start with wilma_summary: today's and tomorrow's lessons, upcoming exams, recent homework, news and messages for every child in one call.
+- Tools cover all children by default; pass "student" (name or student number) to narrow to one child.
+- Wilma content is usually in Finnish. Answer in the user's language and translate as needed.
+- Message and news lists return ids; use wilma_read_message / wilma_read_news for full text. Bulletins can link attachments; fetch them with wilma_get_news_attachment.
+- Teachers' feedback ("forgot books", "did well") and absences are lesson notes: wilma_lesson_notes for recent days, wilma_lesson_notes_summary for counts. Course and report-card grades are in wilma_gradebook.
+- If a tool says the user isn't logged in, relay the login link or instructions to the user exactly; never ask the user to type their Wilma password into the chat.`;
+export const READ_ONLY = { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false };
+const INLINE_ATTACHMENT_LIMIT = 10 * 1024 * 1024;
+const studentArg = z
+    .string()
+    .optional()
+    .describe("Child's name or student number. Omit to include every child on the account.");
+export function json(data) {
+    return { content: [{ type: "text", text: toAgentJson(data) }] };
+}
+export function textResult(text, isError = false) {
+    return { content: [{ type: "text", text }], isError };
+}
+function attachmentResult(fetched, savedPath, inlineLimit = INLINE_ATTACHMENT_LIMIT) {
+    if (fetched.status === "not_a_file") {
+        return json({
+            status: "not_a_file",
+            newsId: fetched.newsId,
+            url: fetched.resource.url,
+            label: fetched.resource.label,
+            message: fetched.message,
+        });
+    }
+    const meta = {
+        status: "fetched",
+        ...(fetched.printoutId ? { printoutId: fetched.printoutId } : { newsId: fetched.newsId, resourceId: fetched.resource.id }),
+        label: fetched.resource.label,
+        fileName: fetched.fileName,
+        contentType: fetched.contentType,
+        sizeBytes: fetched.data.byteLength,
+        savedTo: savedPath ?? null,
+    };
+    const content = [{ type: "text", text: toAgentJson(meta) }];
+    const type = fetched.contentType ?? "application/octet-stream";
+    if (fetched.data.byteLength > inlineLimit) {
+        content.push({
+            type: "text",
+            text: `The file is too large to include here (${(fetched.data.byteLength / 1048576).toFixed(1)} MB). ${fetched.resource.authContext === "wilma" ? "Ask the user to open it in Wilma" : `It can be opened at ${fetched.resource.url}`}${savedPath ? `; a copy was saved to ${savedPath}` : ""}.`,
+        });
+    }
+    else if (/^text\/|json|csv|xml/.test(type)) {
+        content.push({ type: "text", text: fetched.data.toString("utf-8") });
+    }
+    else if (/^image\/(png|jpeg|gif|webp)$/.test(type)) {
+        content.push({ type: "image", data: fetched.data.toString("base64"), mimeType: type });
+    }
+    else {
+        content.push({
+            type: "resource",
+            resource: {
+                uri: fetched.resource.url,
+                mimeType: type,
+                blob: fetched.data.toString("base64"),
+            },
+        });
+    }
+    return { content };
+}
+export function registerWilmaTools(server, ctx) {
+    server.registerTool("wilma_summary", {
+        title: "School summary",
+        description: "Daily briefing per child: today's and the next school day's lessons, upcoming exams (with start times when given), recent homework, lesson notes since the previous school day (teachers' feedback and absences), recent bulletins, and recent and unread messages (ids, unread, replyCount). The best starting point for any question about school.",
+        inputSchema: {
+            student: studentArg,
+            days: z.number().int().min(1).max(60).optional().describe("How many days back to include news and messages (default 7)."),
+            since: z
+                .string()
+                .optional()
+                .describe("Only what is new from this day on (YYYY-MM-DD or 'yesterday'): bulletins, messages, homework, lesson notes. For daily runs."),
+        },
+        annotations: { title: "School summary", ...READ_ONLY },
+    }, async ({ student, days, since }) => ctx.withAccess(async (a) => json(await a.summary({ student, days, since }))));
+    server.registerTool("wilma_schedule", {
+        title: "Lesson schedule",
+        description: "Lessons for today, the next school day, this week, a specific date, or the next occurrence of a weekday.",
+        inputSchema: {
+            student: studentArg,
+            when: z.enum(["today", "tomorrow", "week", "next-week"]).optional().describe("Default: week. 'tomorrow' means the next school day."),
+            date: z.string().optional().describe("A specific date, YYYY-MM-DD. Overrides 'when'."),
+            weekday: z
+                .string()
+                .optional()
+                .describe("Next occurrence of a weekday: mon..sun (Finnish ma..su also work). Overrides 'when'."),
+        },
+        annotations: { title: "Lesson schedule", ...READ_ONLY },
+    }, async ({ student, when, date, weekday }) => ctx.withAccess(async (a) => json(await a.schedule({ student, when, date, weekday }))));
+    server.registerTool("wilma_homework", {
+        title: "Homework",
+        description: "Recent homework entries by lesson, newest first.",
+        inputSchema: { student: studentArg, limit: z.number().int().min(1).max(100).optional() },
+        annotations: { title: "Homework", ...READ_ONLY },
+    }, async ({ student, limit }) => ctx.withAccess(async (a) => json(await a.homework({ student, limit }))));
+    server.registerTool("wilma_upcoming_exams", {
+        title: "Upcoming exams",
+        description: "Upcoming exams with subject, date and topic (what to study).",
+        inputSchema: { student: studentArg, limit: z.number().int().min(1).max(100).optional() },
+        annotations: { title: "Upcoming exams", ...READ_ONLY },
+    }, async ({ student, limit }) => ctx.withAccess(async (a) => json(await a.upcomingExams({ student, limit }))));
+    server.registerTool("wilma_grades", {
+        title: "Exam grades",
+        description: "Recent exam grades.",
+        inputSchema: { student: studentArg, limit: z.number().int().min(1).max(100).optional() },
+        annotations: { title: "Exam grades", ...READ_ONLY },
+    }, async ({ student, limit }) => ctx.withAccess(async (a) => json(await a.grades({ student, limit }))));
+    server.registerTool("wilma_lesson_notes", {
+        title: "Lesson notes and absences",
+        description: "Lesson notes (merkinnät) teachers logged: absences, lateness, and feedback such as praise or missing books or homework, with the teacher's own words when given. One day (default today) or the last N days.",
+        inputSchema: {
+            student: studentArg,
+            date: z.string().optional().describe("YYYY-MM-DD, default today."),
+            days: z.number().int().min(1).max(365).optional().describe("The last N days up to today, instead of one date."),
+        },
+        annotations: { title: "Lesson notes and absences", ...READ_ONLY },
+    }, async ({ student, date, days }) => ctx.withAccess(async (a) => json(await a.lessonNotes({ student, date, days }))));
+    server.registerTool("wilma_lesson_notes_summary", {
+        title: "Absences and feedback summary",
+        description: "Lesson notes counted by kind (e.g. absences for health reasons, unexplained absences, lateness, praise, missing study materials): this school year by default, or from a date.",
+        inputSchema: {
+            student: studentArg,
+            from: z.string().optional().describe("YYYY-MM-DD. Default: the start of the school year."),
+            to: z.string().optional().describe("YYYY-MM-DD. Default: today."),
+        },
+        annotations: { title: "Absences and feedback summary", ...READ_ONLY },
+    }, async ({ student, from, to }) => ctx.withAccess(async (a) => json(await a.lessonNotesSummary({ student, from, to }))));
+    server.registerTool("wilma_gradebook", {
+        title: "Gradebook",
+        description: "Completed courses and grades (Suoritukset) by subject, including term and school-year (report card) grades, with completion dates.",
+        inputSchema: { student: studentArg },
+        annotations: { title: "Gradebook", ...READ_ONLY },
+    }, async ({ student }) => ctx.withAccess(async (a) => json(await a.gradebook({ student }))));
+    server.registerTool("wilma_list_printouts", {
+        title: "List printouts",
+        description: "PDF documents the school offers (Tulosteet), such as report cards or absence reports. Fetch one with wilma_get_printout.",
+        inputSchema: { student: studentArg },
+        annotations: { title: "List printouts", ...READ_ONLY },
+    }, async ({ student }) => ctx.withAccess(async (a) => json(await a.printouts({ student }))));
+    server.registerTool("wilma_get_printout", {
+        title: "Get printout",
+        description: "Fetch one printout PDF so you can read it." +
+            (ctx.saveAttachment ? " Set save=true to also save it to the user's Downloads folder." : ""),
+        inputSchema: {
+            id: z.string().describe("Printout id from wilma_list_printouts."),
+            student: studentArg.describe("The student the printout was listed under."),
+            ...(ctx.saveAttachment ? { save: z.boolean().optional().describe("Also save the file to ~/Downloads/WilmAI.") } : {}),
+        },
+        annotations: {
+            title: "Get printout",
+            readOnlyHint: !ctx.saveAttachment,
+            destructiveHint: false,
+            idempotentHint: !ctx.saveAttachment,
+            openWorldHint: false,
+        },
+    }, async (args) => ctx.withAccess(async (a) => {
+        const fetched = await a.printout({ id: args.id, student: args.student });
+        const savedPath = args.save && ctx.saveAttachment && fetched.status === "fetched" ? await ctx.saveAttachment(fetched) : undefined;
+        return attachmentResult(fetched, savedPath, ctx.inlineAttachmentLimit);
+    }));
+    server.registerTool("wilma_list_messages", {
+        title: "List messages",
+        description: "Wilma messages, newest first (subject, sender, date, id). Use wilma_read_message for the full text.",
+        inputSchema: {
+            student: studentArg,
+            folder: z.enum(["inbox", "archive", "outbox", "drafts", "appointments"]).optional().describe("Default: inbox."),
+            limit: z.number().int().min(1).max(100).optional(),
+        },
+        annotations: { title: "List messages", ...READ_ONLY },
+    }, async ({ student, folder, limit }) => ctx.withAccess(async (a) => json(await a.messages({ student, folder, limit }))));
+    server.registerTool("wilma_read_message", {
+        title: "Read message",
+        description: "Full text of one Wilma message, including thread replies.",
+        inputSchema: {
+            id: z.number().int().positive().describe("Message id from a list."),
+            student: studentArg.describe("The student the message was listed under (required when several Wilmas are connected)."),
+        },
+        annotations: { title: "Read message", ...READ_ONLY },
+    }, async ({ id, student }) => ctx.withAccess(async (a) => json(await a.message({ id, student }))));
+    server.registerTool("wilma_list_news", {
+        title: "List school news",
+        description: "School bulletins (tiedotteet): the newest dated ones, then pinned ones (pinned: true, e.g. the school-year bulletin), and with include_older also older bulletins (archived: true). Use wilma_read_news for the full text and attachments.",
+        inputSchema: {
+            student: studentArg,
+            limit: z.number().int().min(1).max(100).optional().describe("How many dated bulletins (default 20). Pinned ones are always included."),
+            include_older: z.boolean().optional().describe("Also list older bulletins (titles only until read)."),
+        },
+        annotations: { title: "List school news", ...READ_ONLY },
+    }, async ({ student, limit, include_older }) => ctx.withAccess(async (a) => json(await a.news({ student, limit, includeOlder: include_older }))));
+    server.registerTool("wilma_read_news", {
+        title: "Read news bulletin",
+        description: "Full text of one bulletin plus its linked resources (attachments and links). Fetch a resource with wilma_get_news_attachment.",
+        inputSchema: {
+            id: z.number().int().positive().describe("News id from a list."),
+            student: studentArg.describe("The student the bulletin was listed under (required when several Wilmas are connected)."),
+        },
+        annotations: { title: "Read news bulletin", ...READ_ONLY },
+    }, async ({ id, student }) => ctx.withAccess(async (a) => json(await a.newsItem({ id, student }))));
+    server.registerTool("wilma_get_news_attachment", {
+        title: "Get bulletin attachment",
+        description: "Fetch a file linked from a bulletin (e.g. a PDF letter or menu) so you can read it. Returns the file content when it is a file, or 'not_a_file' with the URL when the link is a web page." +
+            (ctx.saveAttachment ? " Set save=true to also save it to the user's Downloads folder." : ""),
+        inputSchema: {
+            news_id: z.number().int().positive(),
+            resource_id: z.string().describe("Resource id from wilma_read_news, e.g. resource-1 (or just 1)."),
+            student: studentArg,
+            ...(ctx.saveAttachment ? { save: z.boolean().optional().describe("Also save the file to ~/Downloads/WilmAI.") } : {}),
+        },
+        annotations: {
+            title: "Get bulletin attachment",
+            readOnlyHint: !ctx.saveAttachment,
+            destructiveHint: false,
+            idempotentHint: !ctx.saveAttachment,
+            openWorldHint: true,
+        },
+    }, async (args) => ctx.withAccess(async (a) => {
+        const fetched = await a.newsAttachment({
+            newsId: args.news_id,
+            resourceId: normalizeResourceId(args.resource_id) ?? args.resource_id,
+            student: args.student,
+        });
+        const savedPath = args.save && ctx.saveAttachment && fetched.status === "fetched" ? await ctx.saveAttachment(fetched) : undefined;
+        return attachmentResult(fetched, savedPath, ctx.inlineAttachmentLimit);
+    }));
+}

package/dist/mcp.d.ts

@@ -0,0 +1 @@
+export declare function runMcpServer(version: string): Promise<void>;

package/dist/mcp.js

@@ -0,0 +1,153 @@
+import { mkdir, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { resolve } from "node:path";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { AuthenticationError } from "@wilm-ai/wilma-client";
+import { useSessionStore } from "./agent-data.js";
+import { fileSessionStore } from "./session-store.js";
+import { createAccess } from "./access.js";
+import { loadConfig } from "./config.js";
+import { ENV_VARS, isMfaFailure, resolveAccounts } from "./credentials.js";
+import { createUniqueDownloadFile } from "./downloads.js";
+import { openBrowser, startLoginServer } from "./login-server.js";
+import { z } from "zod";
+import { INSTRUCTIONS, READ_ONLY, json, registerWilmaTools, textResult } from "./mcp-tools.js";
+import { searchTenants } from "./tenant-search.js";
+const SECRET_SETTINGS_HINT = [
+    "If the user is not at this computer (for example, this agent runs on a cloud computer), the link won't work for them. Instead:",
+    "  1. Ask which city their children's school is in (or the school's name), call wilma_find_school, and let them pick their Wilma from the results.",
+    `  2. Ask them to add their Wilma login to this agent's secret or environment settings: ${ENV_VARS.username}=<username>, ${ENV_VARS.password}=<password>`,
+    `     (${ENV_VARS.totpSecret}=<authenticator setup key> if the account uses two-step verification), and set ${ENV_VARS.tenant} to the Wilma address they picked.`,
+    "Never ask the user to type their Wilma password into the chat.",
+].join("\n");
+let loginServerPromise = null;
+/** One login page at a time. Parallel tool calls share it; an explicit wilma_login starts a fresh one. */
+async function ensureLoginServer(fresh) {
+    if (fresh && loginServerPromise) {
+        (await loginServerPromise).close();
+        loginServerPromise = null;
+    }
+    if (loginServerPromise)
+        return { server: await loginServerPromise, created: false };
+    const pending = startLoginServer().then((server) => {
+        server.result.finally(() => {
+            if (loginServerPromise === pending)
+                loginServerPromise = null;
+        });
+        return server;
+    });
+    loginServerPromise = pending;
+    return { server: await pending, created: true };
+}
+async function startBrowserLogin(requested = false) {
+    const { server, created } = await ensureLoginServer(requested);
+    const opened = created ? openBrowser(server.url) : "skipped";
+    if (opened === "headless") {
+        server.close();
+        return textResult(["Not logged in to Wilma, and this computer has no browser.", SECRET_SETTINGS_HINT].join("\n"), true);
+    }
+    const lead = requested ? "" : "The user is not logged in to Wilma yet. ";
+    return textResult([
+        opened === "opened"
+            ? `${lead}A login page has opened in the user's browser:`
+            : created
+                ? `${lead}Ask the user to open this login page in a browser on this computer:`
+                : `${lead}A login page is already open (if the user can't find it, they can open this link on this computer):`,
+        server.url,
+        "They pick their school's Wilma and log in there; the password never goes through the chat. Then try again.",
+        "",
+        SECRET_SETTINGS_HINT,
+    ].join("\n"), !requested);
+}
+async function withAccess(run) {
+    const config = await loadConfig();
+    let accounts;
+    try {
+        accounts = await resolveAccounts(config);
+    }
+    catch (err) {
+        return textResult(err instanceof Error ? err.message : String(err), true);
+    }
+    if (!accounts.length)
+        return startBrowserLogin();
+    const access = createAccess(accounts);
+    try {
+        return await run(access);
+    }
+    catch (err) {
+        if (isMfaFailure(err)) {
+            return textResult("Wilma rejected the two-step verification code; the saved authenticator setup key may be wrong. Call wilma_login to log in again.", true);
+        }
+        if (err instanceof AuthenticationError) {
+            return textResult("Wilma rejected the saved login (the password may have changed). Call wilma_login to log in again.", true);
+        }
+        return textResult(err instanceof Error ? err.message : String(err), true);
+    }
+}
+function createWilmaMcpServer(version) {
+    const server = new McpServer({ name: "wilma", title: "WilmAI", version }, { instructions: INSTRUCTIONS });
+    registerWilmaTools(server, {
+        withAccess,
+        saveAttachment: async (fetched) => {
+            const directory = resolve(homedir(), "Downloads", "WilmAI");
+            await mkdir(directory, { recursive: true });
+            const { path, handle } = await createUniqueDownloadFile(directory, fetched.fileName);
+            await handle.close();
+            await writeFile(path, fetched.data);
+            return path;
+        },
+    });
+    server.registerTool("wilma_account", {
+        title: "Wilma account status",
+        description: "Which Wilma logins are connected and which children each one has. Families with children on different Wilmas can connect several (wilma_login adds another).",
+        inputSchema: {},
+        annotations: { title: "Wilma account status", ...READ_ONLY },
+    }, async () => {
+        const config = await loadConfig();
+        const accounts = await resolveAccounts(config);
+        if (!accounts.length)
+            return json({ connected: false, hint: "Call wilma_login to connect." });
+        return withAccess(async (a) => {
+            const students = await a.students();
+            return json({
+                connected: true,
+                source: accounts[0].source,
+                wilmas: accounts.map((account, index) => ({
+                    wilma: account.stored?.tenantName ?? account.profile.baseUrl,
+                    username: account.profile.username,
+                    children: students.filter((s) => s.account === index && s.name).map((s) => ({ name: s.name, studentNumber: s.studentNumber })),
+                })),
+                ...(a.problems.length ? { problems: a.problems } : {}),
+            });
+        });
+    });
+    server.registerTool("wilma_find_school", {
+        title: "Find a school's Wilma",
+        description: "Search Finland's Wilma addresses by city or by school or organisation name. Most city schools share their city's Wilma (big cities don't list each school), while many colleges, private schools and small municipalities' schools have their own. Use it to help the user pick their Wilma, e.g. when setting WILMA_TENANT; several can serve one city, so ask which is theirs.",
+        inputSchema: { query: z.string().min(1).describe("City, municipality or school name, e.g. Tampere or Kalevan lukio.") },
+        annotations: { title: "Find a school's Wilma", ...READ_ONLY },
+    }, async ({ query }) => {
+        const found = await searchTenants(query, 15);
+        return json({
+            wilmas: found.map((t) => ({ url: t.url, name: t.name })),
+            ...(found.length ? {} : { hint: `No Wilma found for "${query}". Many schools use their city's Wilma: try the city or municipality the school is in.` }),
+        });
+    });
+    server.registerTool("wilma_login", {
+        title: "Log in to Wilma",
+        description: "Open a login page in the user's browser to connect a Wilma account, or add another one (for a child at a school with a different Wilma). The password is entered on that page, never in the chat.",
+        inputSchema: {},
+        annotations: { title: "Log in to Wilma", readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: false },
+    }, async () => startBrowserLogin(true));
+    return server;
+}
+export async function runMcpServer(version) {
+    // stdout carries JSON-RPC; route any stray logging to stderr.
+    console.log = (...args) => console.error(...args);
+    console.info = (...args) => console.error(...args);
+    // Share saved sessions with the CLI: no login per process, no extra codes.
+    useSessionStore(fileSessionStore);
+    const server = createWilmaMcpServer(version);
+    await server.connect(new StdioServerTransport());
+}

package/dist/output-json.d.ts

@@ -0,0 +1 @@
+export declare function toAgentJson(value: unknown, pretty?: boolean): string;

package/dist/output-json.js

@@ -0,0 +1,26 @@
+import { finnishIsoString } from "@wilm-ai/wilma-client";
+/*
+ * JSON as agents get it, from the CLI and the MCP tools alike:
+ * - times in Finnish time with their offset ("2026-10-02T13:37:00+03:00"), so
+ *   nobody reads UTC as the time on the school's clock;
+ * - no bookkeeping fields that cost tokens and say nothing (when the client
+ *   fetched an item, Wilma's internal type classes and sender ids);
+ * - compact unless asked for pretty output.
+ */
+const NOISE = new Set(["fetchedAt", "typeClass", "sendersJson", "senderId", "senderType"]);
+export function toAgentJson(value, pretty = false) {
+    return JSON.stringify(value, function (key, converted) {
+        if (NOISE.has(key))
+            return undefined;
+        const raw = this[key];
+        // Wilma's numeric message status; `unread` says the same in words.
+        if (key === "status" && typeof raw === "number")
+            return undefined;
+        if (raw instanceof Date) {
+            const time = raw.getTime();
+            // Unknown timestamps are kept as the epoch internally.
+            return Number.isNaN(time) || time <= 0 ? null : finnishIsoString(raw);
+        }
+        return converted;
+    }, pretty ? 2 : undefined);
+}

package/dist/session-store.d.ts

@@ -0,0 +1,7 @@
+export interface SessionStore {
+    load(key: string): Promise<string | null>;
+    save(key: string, state: string): Promise<void>;
+}
+export declare const fileSessionStore: SessionStore;
+/** Forget every saved session (after removing logins or clearing the config). */
+export declare function clearSessions(): Promise<void>;

package/dist/session-store.js

@@ -0,0 +1,61 @@
+import { mkdir, readFile, rename, rm, writeFile } from "node:fs/promises";
+import { randomBytes } from "node:crypto";
+import { dirname, resolve } from "node:path";
+import { getConfigPath } from "./config.js";
+/*
+ * Wilma sessions saved between commands. Wilma allows one live session per
+ * account and every login cancels the previous one — which also logs the
+ * parent out of Wilma in their own browser, and with two-step verification
+ * needs a fresh code. So commands (and the local MCP server) continue the last
+ * session instead of logging in each time, and log in again only when Wilma
+ * has ended it.
+ *
+ * A saved session gives the same access as the saved password, so it lives
+ * next to it with the same protection: a file only this user can read. Set
+ * WILMAI_NO_SESSION_CACHE=1 to log in on every command instead.
+ */
+/** A session older than this is not tried (Wilma ends idle sessions anyway). */
+const SESSION_TTL_MS = 6 * 60 * 60 * 1000;
+function sessionsPath() {
+    return resolve(dirname(getConfigPath()), "wilmai-sessions.json");
+}
+async function readAll() {
+    try {
+        const data = JSON.parse(await readFile(sessionsPath(), "utf8"));
+        return data && typeof data === "object" ? data : {};
+    }
+    catch {
+        return {};
+    }
+}
+export const fileSessionStore = {
+    async load(key) {
+        if (process.env.WILMAI_NO_SESSION_CACHE === "1")
+            return null;
+        const entry = (await readAll())[key];
+        if (!entry || typeof entry.state !== "string" || Date.now() - entry.savedAt > SESSION_TTL_MS)
+            return null;
+        return entry.state;
+    },
+    async save(key, state) {
+        if (process.env.WILMAI_NO_SESSION_CACHE === "1")
+            return;
+        const all = await readAll();
+        const now = Date.now();
+        for (const [k, entry] of Object.entries(all)) {
+            if (now - entry.savedAt > SESSION_TTL_MS)
+                delete all[k];
+        }
+        all[key] = { state, savedAt: now };
+        const path = sessionsPath();
+        await mkdir(dirname(path), { recursive: true, mode: 0o700 });
+        // Temp file + rename: a parallel command never reads half a file.
+        const tmp = `${path}.${process.pid}.${randomBytes(4).toString("hex")}.tmp`;
+        await writeFile(tmp, JSON.stringify(all), { encoding: "utf-8", mode: 0o600 });
+        await rename(tmp, path);
+    },
+};
+/** Forget every saved session (after removing logins or clearing the config). */
+export async function clearSessions() {
+    await rm(sessionsPath(), { force: true });
+}

package/dist/tenant-search.d.ts

@@ -0,0 +1,11 @@
+import { type TenantInfo } from "@wilm-ai/wilma-client";
+/** Rank a tenant list against a query (pure; for callers that load the list themselves). */
+export declare function rankTenants(tenants: TenantInfo[], query: string, limit?: number): TenantInfo[];
+export declare function searchTenants(query: string, limit?: number): Promise<TenantInfo[]>;
+/** Canonical form of a Wilma address: lowercase scheme and host, no trailing slash. */
+export declare function normalizeTenantUrl(value: string): string;
+/**
+ * Resolve a tenant from a URL or a school/city name for non-interactive use.
+ * Throws with the candidate list when the name is ambiguous.
+ */
+export declare function resolveTenant(query: string): Promise<TenantInfo>;

package/dist/tenant-search.js

@@ -0,0 +1,127 @@
+import { listTenants } from "@wilm-ai/wilma-client";
+function municipalityNames(tenant) {
+    const list = (Array.isArray(tenant.municipalities) ? tenant.municipalities : []);
+    const names = [];
+    for (const m of list) {
+        if (!m)
+            continue;
+        for (const value of [m.nameFi, m.nameSv, m.name_fi, m.name_sv]) {
+            if (value)
+                names.push(value);
+        }
+    }
+    return names;
+}
+function fuzzyIncludes(target, needle) {
+    const hay = (target ?? "").toLowerCase();
+    const search = (needle ?? "").toLowerCase();
+    if (!search)
+        return true;
+    if (hay.includes(search))
+        return true;
+    let i = 0;
+    for (const ch of hay) {
+        if (ch === search[i]) {
+            i += 1;
+            if (i >= search.length)
+                return true;
+        }
+    }
+    return false;
+}
+function tenantMatches(search, tenant) {
+    const needle = (search ?? "").toLowerCase();
+    if (fuzzyIncludes(tenant.name ?? "", needle))
+        return true;
+    if (fuzzyIncludes(tenant.url ?? "", needle))
+        return true;
+    return municipalityNames(tenant).some((name) => fuzzyIncludes(name, needle));
+}
+/**
+ * 0 = subdomain or name equals the query (a city's own Wilma),
+ * 1 = municipality equals it, 2 = prefix, 3 = substring, 4 = fuzzy, null = no match.
+ */
+function matchRank(search, tenant) {
+    const needle = search.trim().toLowerCase();
+    const host = (tenant.url ?? "").replace(/^https?:\/\//, "").toLowerCase();
+    const subdomain = host.split(".")[0] ?? "";
+    const name = (tenant.name ?? "").toLowerCase();
+    const municipalities = municipalityNames(tenant).map((m) => m.toLowerCase());
+    const fields = [name, subdomain, ...municipalities];
+    if (subdomain === needle || name === needle)
+        return 0;
+    if (municipalities.includes(needle))
+        return 1;
+    if (fields.some((f) => f.startsWith(needle)))
+        return 2;
+    if (fields.some((f) => f.includes(needle)) || host.includes(needle))
+        return 3;
+    if (tenantMatches(needle, tenant))
+        return 4;
+    return null;
+}
+// Within a rank, list a municipality's own school Wilma before private schools,
+// institutes and colleges — that's the one most parents are looking for.
+function municipalBias(tenant) {
+    return /kaupun|kunta|kunnan|perusopetus|opetustoimi|sivistys/i.test(tenant.name ?? "") ? 0 : 1;
+}
+/** Rank a tenant list against a query (pure; for callers that load the list themselves). */
+export function rankTenants(tenants, query, limit = 20) {
+    const needle = (query ?? "").trim();
+    if (!needle)
+        return tenants.slice(0, limit);
+    const ranked = tenants
+        .map((tenant) => ({ tenant, rank: matchRank(needle, tenant) }))
+        .filter((entry) => entry.rank !== null);
+    // Loose letter-by-letter matches ("espoo" inside "Joensuun ... opetus") are only
+    // a fallback for typos; never mix them into real results.
+    const hasRealMatch = ranked.some((entry) => entry.rank < 4);
+    return ranked
+        .filter((entry) => !hasRealMatch || entry.rank < 4)
+        .sort((a, b) => a.rank - b.rank ||
+        municipalBias(a.tenant) - municipalBias(b.tenant) ||
+        (a.tenant.name ?? "").localeCompare(b.tenant.name ?? "", "fi"))
+        .slice(0, limit)
+        .map((entry) => entry.tenant);
+}
+export async function searchTenants(query, limit = 20) {
+    return rankTenants(await listTenants(), query, limit);
+}
+/** Canonical form of a Wilma address: lowercase scheme and host, no trailing slash. */
+export function normalizeTenantUrl(value) {
+    const trimmed = value.trim();
+    try {
+        const url = new URL(trimmed);
+        return `${url.origin}${url.pathname}`.replace(/\/$/, "");
+    }
+    catch {
+        return trimmed.replace(/\/$/, "");
+    }
+}
+/**
+ * Resolve a tenant from a URL or a school/city name for non-interactive use.
+ * Throws with the candidate list when the name is ambiguous.
+ */
+export async function resolveTenant(query) {
+    const value = (query ?? "").trim();
+    if (!value)
+        throw new Error("Missing Wilma address (a URL like https://<school>.inschool.fi or a city name).");
+    if (/^https?:\/\//i.test(value)) {
+        const url = normalizeTenantUrl(value);
+        const tenants = await listTenants();
+        return tenants.find((t) => normalizeTenantUrl(t.url) === url) ?? { url, name: url, municipalities: [] };
+    }
+    const tenants = await listTenants();
+    const ranked = tenants
+        .map((tenant) => ({ tenant, rank: matchRank(value, tenant) }))
+        .filter((entry) => entry.rank !== null && entry.rank <= 3);
+    const best = Math.min(...ranked.map((entry) => entry.rank));
+    const top = ranked.filter((entry) => entry.rank === best).map((entry) => entry.tenant);
+    if (top.length === 1)
+        return top[0];
+    if (!top.length) {
+        throw new Error(`No Wilma found for "${value}". Many schools use their city's Wilma: try the city or municipality the school is in. Or use the full address, e.g. https://<school>.inschool.fi`);
+    }
+    const options = top.slice(0, 10).map((t) => `  ${t.url}  ${t.name}`).join("\n");
+    throw new Error(`"${value}" matches several Wilmas. Use the address instead:\n${options}`);
+}