@wilm-ai/wilma-cli 1.6.2 → 2.0.1

package/dist/cli-args.js

@@ -0,0 +1,256 @@
+import { SCHEDULE_WHEN, WilmaAiError, parseIsoDate } from "./agent-data.js";
+import { normalizeResourceId } from "./downloads.js";
+const DATA_COMMANDS = [
+    "summary",
+    "schedule",
+    "homework",
+    "exams",
+    "grades",
+    "gradebook",
+    "notes",
+    "messages",
+    "news",
+    "printouts",
+    "students",
+];
+const OTHER_COMMANDS = ["accounts", "find-school", "login", "mcp", "update", "config", "help"];
+const ALIASES = {
+    kids: "students",
+    tenants: "find-school",
+    attendance: "notes",
+    "lesson-notes": "notes",
+    absences: "notes",
+    exam: "exams",
+    message: "messages",
+};
+const MESSAGE_FOLDERS = ["inbox", "archive", "outbox", "drafts", "appointments"];
+const WEEKDAY_WORDS = /^(mon|tue|wed|thu|fri|sat|sun|ma|ti|ke|to|pe|la|su|monday|tuesday|wednesday|thursday|friday|saturday|sunday)$/i;
+const usage = (message) => new WilmaAiError("invalid_argument", `${message} See wilma --help.`);
+export function parseCliArgs(argv) {
+    const flags = {};
+    const positionals = [];
+    const first = argv.find((arg) => !arg.startsWith("-"));
+    const firstCommand = first ? (ALIASES[first] ?? first) : null;
+    // Login and the MCP server take their own options.
+    if (firstCommand === "login" || firstCommand === "mcp") {
+        const at = argv.indexOf(first);
+        const raw = argv.slice(at + 1);
+        return { command: firstCommand, action: null, args: [], flags: { json: raw.includes("--json") }, raw };
+    }
+    const value = (i) => {
+        const next = argv[i + 1];
+        if (next === undefined || next.startsWith("--"))
+            throw usage(`${argv[i]} needs a value.`);
+        return next;
+    };
+    const positiveInt = (i, max) => {
+        const raw = value(i);
+        const n = Number(raw);
+        if (!Number.isInteger(n) || n < 1 || n > max)
+            throw usage(`${argv[i]} must be a whole number from 1 to ${max} (got "${raw}").`);
+        return n;
+    };
+    for (let i = 0; i < argv.length; i += 1) {
+        const arg = argv[i];
+        const take = () => {
+            const v = value(i);
+            i += 1;
+            return v;
+        };
+        switch (arg) {
+            case "--json":
+                flags.json = true;
+                break;
+            case "--text":
+                flags.text = true;
+                break;
+            case "--debug":
+                flags.debug = true;
+                break;
+            case "--older":
+                flags.older = true;
+                break;
+            case "--help":
+            case "-h":
+                flags.help = true;
+                break;
+            case "--version":
+            case "-v":
+                flags.version = true;
+                break;
+            case "--all-students":
+            case "--all":
+                // Every child is the default now; accepted for 1.x commands.
+                break;
+            case "--student":
+                flags.student = take();
+                break;
+            case "--limit":
+                flags.limit = positiveInt(i, 1000);
+                i += 1;
+                break;
+            case "--days":
+                flags.days = positiveInt(i, 365);
+                i += 1;
+                break;
+            case "--since":
+                flags.since = parseIsoDate(take());
+                break;
+            case "--from":
+                flags.from = parseIsoDate(take());
+                break;
+            case "--to":
+                flags.to = parseIsoDate(take());
+                break;
+            case "--date":
+                flags.date = parseIsoDate(take());
+                break;
+            case "--when": {
+                const when = take();
+                if (!SCHEDULE_WHEN.includes(when))
+                    throw usage(`--when must be one of ${SCHEDULE_WHEN.join(", ")} (got "${when}").`);
+                flags.when = when;
+                break;
+            }
+            case "--weekday":
+                flags.weekday = take();
+                break;
+            case "--folder": {
+                const folder = take();
+                if (!MESSAGE_FOLDERS.includes(folder))
+                    throw usage(`--folder must be one of ${MESSAGE_FOLDERS.join(", ")} (got "${folder}").`);
+                flags.folder = folder;
+                break;
+            }
+            case "--output":
+                flags.output = take();
+                break;
+            case "--totp-secret":
+                flags.totpSecret = take();
+                break;
+            default:
+                if (arg.startsWith("-"))
+                    throw usage(`Unknown option "${arg}".`);
+                positionals.push(arg);
+        }
+    }
+    if (flags.json && flags.text)
+        throw usage("Use either --json or --text.");
+    if (!positionals.length)
+        return { command: null, action: null, args: [], flags, raw: argv };
+    const [name, ...rest] = positionals;
+    const command = ALIASES[name] ?? name;
+    if (!DATA_COMMANDS.includes(command) && !OTHER_COMMANDS.includes(command)) {
+        throw new WilmaAiError("unknown_command", `Unknown command "${name}". See wilma --help.`);
+    }
+    // `<command> list` is the 1.x spelling of the default action.
+    const args = rest[0] === "list" ? rest.slice(1) : rest;
+    const parsed = (action, values = []) => ({ command, action, args: values, flags, raw: argv });
+    const noMore = (extra) => {
+        if (extra.length)
+            throw usage(`Unexpected "${extra.join(" ")}" after ${command}.`);
+    };
+    switch (command) {
+        case "schedule": {
+            const [period, ...extra] = args;
+            noMore(extra);
+            if (period) {
+                if (SCHEDULE_WHEN.includes(period))
+                    flags.when = period;
+                else if (WEEKDAY_WORDS.test(period))
+                    flags.weekday = period;
+                else if (/^\d{4}-\d{2}-\d{2}$/.test(period) || period === "yesterday")
+                    flags.date = parseIsoDate(period);
+                else
+                    throw usage(`Unknown period "${period}". Use today, tomorrow, week, next-week, a date (YYYY-MM-DD) or a weekday.`);
+            }
+            return parsed(null);
+        }
+        case "notes": {
+            if (args[0] === "summary") {
+                noMore(args.slice(1));
+                return parsed("summary");
+            }
+            noMore(args);
+            return parsed(null);
+        }
+        case "messages": {
+            const [first, second, ...extra] = args;
+            if (first === "read") {
+                noMore(extra);
+                return parsed("read", [checkId(second, "message")]);
+            }
+            if (first !== undefined) {
+                noMore([second, ...extra].filter((x) => x !== undefined));
+                return parsed("read", [checkId(first, "message")]);
+            }
+            return parsed(null);
+        }
+        case "news": {
+            const [first, second, third, fourth, ...extra] = args;
+            if (first === "read") {
+                noMore([third, fourth, ...extra].filter((x) => x !== undefined));
+                return parsed("read", [checkId(second, "news")]);
+            }
+            if (first === "resource") {
+                if (second !== "download")
+                    throw usage('Expected "wilma news <id> download <resource>".');
+                noMore(extra);
+                return parsed("download", [checkId(third, "news"), checkResource(fourth)]);
+            }
+            if (first !== undefined) {
+                const id = checkId(first, "news");
+                if (second === undefined)
+                    return parsed("read", [id]);
+                if (second !== "download")
+                    throw usage(`Unexpected "${second}" after news ${first}.`);
+                noMore([fourth, ...extra].filter((x) => x !== undefined));
+                return parsed("download", [id, checkResource(third)]);
+            }
+            return parsed(null);
+        }
+        case "printouts": {
+            const [first, second, ...extra] = args;
+            if (first === "download") {
+                noMore(extra);
+                return parsed("download", [checkId(second, "printout")]);
+            }
+            if (first !== undefined) {
+                noMore([second, ...extra].filter((x) => x !== undefined));
+                return parsed("download", [checkId(first, "printout")]);
+            }
+            return parsed(null);
+        }
+        case "accounts":
+            if (args[0] === "remove")
+                return parsed("remove", args.slice(1));
+            noMore(args);
+            return parsed(null);
+        case "config":
+            if (args[0] !== "clear" || args.length > 1)
+                throw usage('Expected "wilma config clear".');
+            return parsed("clear");
+        case "find-school":
+            if (!args.length)
+                throw usage('Expected "wilma find-school <city or school>".');
+            return parsed(null, args);
+        case "help":
+            return parsed(null, args.slice(0, 1).map((topic) => ALIASES[topic] ?? topic));
+        default:
+            noMore(args);
+            return parsed(null);
+    }
+}
+function checkId(raw, entity) {
+    if (!raw)
+        throw usage(`Missing ${entity} id.`);
+    if (!/^\d+$/.test(raw) || Number(raw) <= 0)
+        throw usage(`Invalid ${entity} id "${raw}". Expected a positive whole number.`);
+    return raw;
+}
+function checkResource(raw) {
+    const id = normalizeResourceId(raw);
+    if (!id)
+        throw usage("Missing resource id (e.g. 1, or resource-1 from the bulletin's resources).");
+    return id;
+}

package/dist/cli-help.d.ts

@@ -0,0 +1,2 @@
+export declare function generalHelp(): string;
+export declare function commandHelp(command: string): string | null;

package/dist/cli-help.js

@@ -0,0 +1,141 @@
+import { ENV_VARS } from "./credentials.js";
+const STUDENT = "--student <number|name>";
+const COMMAND_HELP = {
+    summary: {
+        usage: [`wilma summary [--since <date>] [--days 7] [${STUDENT}]`],
+        about: "The daily briefing for every child: today's and the next school day's lessons, upcoming exams (with start times when the school gives one), recent homework, lesson notes since the previous school day (teachers' feedback and absences), recent bulletins, and recent and unread messages. Start here.",
+        examples: ["wilma summary", "wilma summary --since yesterday", `wilma summary --student Kiia`],
+        output: "{ generatedAt, students: [{ student, summary: { today, tomorrow, todaySchedule, tomorrowSchedule, upcomingExams, homework, lessonNotes, news, messages, unreadMessages } }] }. --since <date> keeps only what is from that day on (for daily runs); messages carry unread and replyCount.",
+    },
+    schedule: {
+        usage: [`wilma schedule [today|tomorrow|week|next-week|<YYYY-MM-DD>|<weekday>] [${STUDENT}]`],
+        about: "Lessons with times, teachers and rooms. Default: this week. 'tomorrow' is the next school day; a weekday (mon…sun, or ma…su) is its next occurrence.",
+        examples: ["wilma schedule tomorrow", "wilma schedule next-week", "wilma schedule 2026-10-07", "wilma schedule thu --student Kiia"],
+        output: "{ when, date | weekStart+weekEnd, students: [{ student, lessons: [{ date, start, end, subject, teacher, room }] }] }",
+    },
+    homework: {
+        usage: [`wilma homework [--limit 10] [${STUDENT}]`],
+        about: "Recent homework by lesson, newest first.",
+        examples: ["wilma homework", "wilma homework --limit 30"],
+    },
+    exams: {
+        usage: [`wilma exams [--limit 20] [${STUDENT}]`],
+        about: "Upcoming exams with subject, name, topic (what to study), teacher and the start time when the school gives one.",
+        examples: ["wilma exams"],
+        output: "{ students: [{ student, exams: [{ date, time, subject, name, topic, teacher }] }] }",
+    },
+    grades: {
+        usage: [`wilma grades [--limit 20] [${STUDENT}]`],
+        about: "Recent exam grades. For course and report-card grades, see `wilma gradebook`.",
+        examples: ["wilma grades"],
+    },
+    gradebook: {
+        usage: [`wilma gradebook [${STUDENT}]`],
+        about: "Completed courses and grades (Suoritukset) by subject, including term and school-year (report card) grades, with credits and dates.",
+        examples: ["wilma gradebook --student Kiia"],
+        output: "{ students: [{ student, gradebook: [{ name, code, grade, credits, date, children: [...] }] }] }",
+    },
+    notes: {
+        usage: [`wilma notes [--date <date> | --days 14 | --from <date> [--to <date>]] [${STUDENT}]`, `wilma notes summary [--from <date>] [--to <date>] [${STUDENT}]`],
+        about: "Lesson notes (merkinnät) teachers log: absences, lateness, and feedback such as praise or missing books or homework, with the teacher's own words in `note`. One day (default today) or a period. `notes summary` counts them by kind for the school year or a period.",
+        examples: ["wilma notes --date yesterday", "wilma notes --days 14", "wilma notes summary"],
+        output: "{ date | from+to, students: [{ student, notes: [{ date, start, end, subject, typeLabel, teacher, note }] }] }",
+    },
+    messages: {
+        usage: [`wilma messages [--folder inbox|outbox|appointments|archive|drafts] [--limit 20] [${STUDENT}]`, `wilma messages <id> [${STUDENT}]`],
+        about: "Messages, newest first (subject, sender, date, unread, replyCount), or one message with its whole thread of replies.",
+        examples: ["wilma messages", "wilma messages --folder appointments", "wilma messages 27164611"],
+    },
+    news: {
+        usage: [`wilma news [--limit 20] [--older] [${STUDENT}]`, `wilma news <id> [${STUDENT}]`, `wilma news <id> download <resource> [--output <directory>] [${STUDENT}]`],
+        about: "School bulletins (tiedotteet): the newest dated ones and every pinned one (pinned: true); --older adds older bulletins (archived: true). `news <id>` reads one, with its linked resources; `download` fetches a resource (a file, or not_a_file when the link is a web page).",
+        examples: ["wilma news", "wilma news 73291", "wilma news 73291 download 1 --output ./attachments"],
+    },
+    printouts: {
+        usage: [`wilma printouts [${STUDENT}]`, `wilma printouts <id> [--output <directory>] [${STUDENT}]`],
+        about: "PDF documents the school offers (Tulosteet), such as report cards or absence reports; `printouts <id>` downloads one.",
+        examples: ["wilma printouts", "wilma printouts 24719 --output ~/Downloads"],
+    },
+    students: {
+        usage: ["wilma students"],
+        about: "The children on the saved logins (number, name, and their Wilma when there are several).",
+        examples: ["wilma students"],
+    },
+    login: {
+        usage: ["wilma login [--no-browser]", "wilma login --tenant <url|city> --username <name> [--password-stdin] [--totp-secret <key>]"],
+        about: "Log in to Wilma. Opens a one-time login page in the browser where the parent picks their school's Wilma; logins are saved on this computer. Families with children on different Wilmas add each one there. Without a browser, pass --tenant and --username with the password on stdin or in WILMA_PASSWORD.",
+        examples: ["wilma login"],
+    },
+    accounts: {
+        usage: ["wilma accounts", "wilma accounts remove <number|Wilma name|username>"],
+        about: "Saved Wilma logins, numbered (one per Wilma the children use); remove one.",
+        examples: ["wilma accounts", "wilma accounts remove 2"],
+    },
+    "find-school": {
+        usage: ["wilma find-school <city or school>"],
+        about: "Find a Wilma address. Most city schools share their city's Wilma (big cities don't list each school); colleges, private schools and many small municipalities' schools have their own.",
+        examples: ["wilma find-school tampere", "wilma find-school kalevan lukio"],
+    },
+    mcp: {
+        usage: ["wilma mcp"],
+        about: "Run the MCP server over stdio for Claude, ChatGPT and other assistants (the same data as these commands, as tools).",
+        examples: ["npx -y @wilm-ai/wilma-cli@2 mcp"],
+    },
+    update: { usage: ["wilma update"], about: "Update the CLI with npm.", examples: ["wilma update"] },
+    config: { usage: ["wilma config clear"], about: "Delete every saved login and session on this computer.", examples: ["wilma config clear"] },
+};
+const OVERVIEW = [
+    ["summary", "daily briefing for every child (start here)"],
+    ["schedule [when]", "lessons: today, tomorrow, week, next-week, a date or a weekday"],
+    ["exams", "upcoming exams with topics and start times"],
+    ["homework", "recent homework"],
+    ["notes [summary]", "lesson notes: absences and teachers' feedback; summary counts them"],
+    ["messages [id]", "messages, or one with its replies"],
+    ["news [id [download r]]", "bulletins, one bulletin, or a linked file"],
+    ["grades", "recent exam grades"],
+    ["gradebook", "course and report-card grades"],
+    ["printouts [id]", "PDFs such as report cards"],
+    ["students", "the children"],
+    ["login", "log in (opens a page in the browser)"],
+    ["accounts", "saved logins; accounts remove <n>"],
+    ["find-school <query>", "find a Wilma address by city or school"],
+    ["mcp", "MCP server for AI assistants"],
+    ["update", "update the CLI"],
+];
+export function generalHelp() {
+    const width = Math.max(...OVERVIEW.map(([name]) => name.length));
+    return [
+        "WilmAI: read Finland's Wilma school system (read-only).",
+        "",
+        "Usage: wilma <command> [options]",
+        "",
+        ...OVERVIEW.map(([name, about]) => `  ${name.padEnd(width)}  ${about}`),
+        "",
+        "Every command covers all children; --student <number|name> narrows to one.",
+        "Output is JSON when another program reads it (agents, pipes) and text in a terminal;",
+        "--json or --text forces either. Dates are YYYY-MM-DD (or today, yesterday, tomorrow);",
+        "times in JSON are Finnish time with their offset.",
+        "",
+        "Errors are JSON too: { status: \"error\", code, message } with exit code 2 for usage",
+        "errors, 3 when not logged in, 1 otherwise.",
+        "",
+        `Without a saved login, set ${ENV_VARS.tenant}, ${ENV_VARS.username} and ${ENV_VARS.password}`,
+        `(plus ${ENV_VARS.totpSecret} for two-step verification). The password is never a command-line flag.`,
+        "",
+        "More: wilma help <command>   ·   wilma --version",
+    ].join("\n");
+}
+export function commandHelp(command) {
+    const help = COMMAND_HELP[command];
+    if (!help)
+        return null;
+    return [
+        ...help.usage.map((line, i) => `${i === 0 ? "Usage: " : "       "}${line}`),
+        "",
+        help.about,
+        ...(help.output ? ["", `JSON: ${help.output}`] : []),
+        "",
+        "Examples:",
+        ...help.examples.map((example) => `  ${example}`),
+    ].join("\n");
+}

package/dist/cli-output.d.ts

@@ -0,0 +1,6 @@
+import type { Message, NewsItem } from "@wilm-ai/wilma-client";
+export declare function compactText(value: string | null | undefined): string;
+export declare function newsLine(item: Pick<NewsItem, "wilmaId" | "title" | "published" | "pinned" | "archived">): string;
+export declare function messageLine(msg: Pick<Message, "wilmaId" | "subject" | "sentAt" | "senderName" | "unread" | "replyCount">): string;
+/** Text for a command's result. */
+export declare function formatText(command: string, action: string | null, result: any): string;

package/dist/cli-output.js

@@ -0,0 +1,184 @@
+import { finnishIsoString } from "@wilm-ai/wilma-client";
+const DAY_NAMES = ["Sun", "Mon", "Tue", "Wed", "Thu", "Fri", "Sat"];
+export function compactText(value) {
+    return (value ?? "").replace(/\s+/g, " ").trim();
+}
+/** Multi-line text with single blank lines between blocks. */
+function formatContent(value) {
+    const lines = value
+        .replace(/\r/g, "")
+        .split("\n")
+        .map((line) => line.trim())
+        .filter((line, index, arr) => line !== "" || arr[index - 1] !== "");
+    return lines.join("\n").replace(/\n{3,}/g, "\n\n").trim();
+}
+/** "2026-10-02 13:37" in Finnish time. */
+function finnishDateTime(d) {
+    if (!d || Number.isNaN(d.getTime()) || d.getTime() <= 0)
+        return "";
+    return finnishIsoString(d).slice(0, 16).replace("T", " ");
+}
+function finnishDay(d) {
+    return finnishDateTime(d).slice(0, 10);
+}
+function weekday(isoDate) {
+    return DAY_NAMES[new Date(`${isoDate}T12:00:00Z`).getUTCDay()];
+}
+function heading(student, several) {
+    if (!several)
+        return [];
+    return ["", `${student.name}${student.wilma ? ` (${student.wilma})` : ""}`];
+}
+/** A title line, then the per-child sections (a blank line between when there are several children). */
+function titled(title, result, body) {
+    return result.students.length > 1 ? `${title}\n\n${body}` : `${title}\n${body}`;
+}
+function perStudent(result, key, render) {
+    const several = result.students.length > 1;
+    const lines = [];
+    for (const entry of result.students) {
+        lines.push(...heading(entry.student, several), ...render(entry[key], entry.student));
+    }
+    for (const problem of result.problems ?? [])
+        lines.push("", `Couldn't read ${problem.wilma}: ${problem.message}`);
+    return lines.join("\n").replace(/^\n/, "");
+}
+function lessonLine(l) {
+    const teacher = l.teacher ? ` — ${l.teacher}` : "";
+    const room = l.room ? `, ${l.room}` : "";
+    return `${l.start}-${l.end}  ${l.subject}${teacher}${room}`;
+}
+function examLine(exam) {
+    const when = exam.time ? `${exam.date} ${exam.time}` : exam.date;
+    const topic = exam.topic ? ` — ${compactText(exam.topic)}` : "";
+    return `${when}  ${exam.subject}${exam.name ? `: ${exam.name}` : ""}${topic}`;
+}
+export function newsLine(item) {
+    const date = item.published ? `${finnishDay(item.published)} ` : "";
+    const mark = item.pinned ? " [pinned]" : item.archived ? " [older]" : "";
+    return `${date}${compactText(item.title)}${mark} (id ${item.wilmaId})`;
+}
+export function messageLine(msg) {
+    const sender = msg.senderName ? ` — ${compactText(msg.senderName)}` : "";
+    const replies = msg.replyCount ? ` [${msg.replyCount} ${msg.replyCount === 1 ? "reply" : "replies"}]` : "";
+    return `${finnishDay(msg.sentAt)} ${compactText(msg.subject)}${sender}${msg.unread ? " [new]" : ""}${replies} (id ${msg.wilmaId})`;
+}
+function lessonNoteLine(note, withDate) {
+    const date = withDate ? `${note.date} ` : "";
+    const time = note.start ? `${note.start} ` : "";
+    const subject = note.subject ? ` [${note.subject}]` : "";
+    const teacher = note.teacher ? ` ${note.teacher}` : "";
+    const words = note.note ? `: ${compactText(note.note)}` : "";
+    return `${date}${time}${note.typeLabel}${subject}${teacher}${words}`;
+}
+function scheduleLines(lessons) {
+    if (!lessons.length)
+        return ["  No lessons."];
+    const lines = [];
+    let day = "";
+    for (const lesson of lessons) {
+        if (lesson.date !== day) {
+            day = lesson.date;
+            lines.push(`  ${weekday(day)} ${day}`);
+        }
+        lines.push(`    ${lessonLine(lesson)}`);
+    }
+    return lines;
+}
+function gradebookLines(entries, depth = 0) {
+    if (!entries.length && depth === 0)
+        return ["  No graded courses yet."];
+    return entries.flatMap((entry) => {
+        const code = entry.code ? `${entry.code} ` : "";
+        const grade = entry.grade ? `  ${entry.grade}` : "";
+        const credits = entry.credits ? `  (${entry.credits})` : "";
+        const date = entry.date ? `  ${entry.date}` : "";
+        return [`${"  ".repeat(depth + 1)}${code}${compactText(entry.name)}${grade}${credits}${date}`, ...gradebookLines(entry.children, depth + 1)];
+    });
+}
+function summaryLines(s) {
+    const section = (title, lines, empty) => lines.length ? ["", title, ...lines.map((line) => `  ${line}`)] : empty ? ["", title, `  ${empty}`] : [];
+    return [
+        ...section(`Today ${weekday(s.today)} ${s.today}`, s.todaySchedule.map(lessonLine), "No lessons."),
+        ...section(`Next school day ${weekday(s.tomorrow)} ${s.tomorrow}`, s.tomorrowSchedule.map(lessonLine), "No lessons."),
+        ...section("Upcoming exams", s.upcomingExams.map(examLine)),
+        ...section("Homework", s.homework.map((h) => `${h.date}  ${h.subject}: ${compactText(h.homework)}`)),
+        ...section("Lesson notes", s.lessonNotes.map((n) => lessonNoteLine(n, true))),
+        ...section("Bulletins", s.news.map((n) => newsLine(n))),
+        ...section(`Messages${s.unreadMessages ? ` (${s.unreadMessages} unread)` : ""}`, s.messages.map((m) => messageLine(m))),
+        ...(s.unavailable?.length ? ["", `(Not available from Wilma right now: ${s.unavailable.join(", ")})`] : []),
+    ];
+}
+/** Text for a command's result. */
+export function formatText(command, action, result) {
+    switch (command) {
+        case "summary":
+            return perStudent(result, "summary", (s) => summaryLines(s));
+        case "schedule": {
+            const period = result.weekStart ? `${result.weekStart} – ${result.weekEnd}` : result.date;
+            return titled(`Schedule ${period}`, result, perStudent(result, "lessons", scheduleLines));
+        }
+        case "homework":
+            return perStudent(result, "homework", (items) => items.length ? items.map((h) => `  ${h.date}  ${h.subject}: ${compactText(h.homework)}`) : ["  No recent homework."]);
+        case "exams":
+            return perStudent(result, "exams", (items) => (items.length ? items.map((e) => `  ${examLine(e)}`) : ["  No upcoming exams."]));
+        case "grades":
+            return perStudent(result, "grades", (items) => items.length ? items.map((g) => `  ${g.date}  ${g.subject}: ${g.name} — ${g.grade}`) : ["  No exam grades."]);
+        case "gradebook":
+            return perStudent(result, "gradebook", (entries) => gradebookLines(entries));
+        case "notes": {
+            if (action === "summary") {
+                return perStudent(result, "summary", (s) => [
+                    `  Lesson notes, ${s.from ? `${s.from} – ${s.to}` : "this school year"}: ${s.total}`,
+                    ...s.byType.map((t) => `    ${t.type}: ${t.count}`),
+                ]);
+            }
+            const period = result.from ? `${result.from} – ${result.to}` : result.date;
+            return titled(`Lesson notes ${period}`, result, perStudent(result, "notes", (notes) => notes.length ? notes.map((n) => `  ${lessonNoteLine(n, Boolean(result.from))}`) : ["  No lesson notes."]));
+        }
+        case "messages": {
+            if (action === "read") {
+                const msg = result.message;
+                return [
+                    msg.subject,
+                    ...(msg.senderName ? [`From: ${msg.senderName}`] : []),
+                    ...(msg.recipients?.length ? [`To: ${msg.recipients.join(", ")}`] : []),
+                    `Sent: ${finnishDateTime(msg.sentAt)}`,
+                    ...(msg.content ? ["", formatContent(msg.content)] : []),
+                    ...(msg.replies ?? []).flatMap((reply) => [
+                        "",
+                        `--- Reply from ${reply.senderName ?? "unknown"}, ${finnishDateTime(reply.sentAt)}`,
+                        ...(reply.content ? [formatContent(reply.content)] : []),
+                    ]),
+                ].join("\n");
+            }
+            return perStudent(result, "messages", (items) => (items.length ? items.map((m) => `  ${messageLine(m)}`) : ["  No messages."]));
+        }
+        case "news": {
+            if (action === "read") {
+                const item = result.news;
+                return [
+                    item.title,
+                    ...(item.subtitle ? [item.subtitle] : []),
+                    ...(item.published ? [`Published: ${finnishDay(item.published)}${item.author ? ` by ${item.author}` : ""}`] : []),
+                    ...(item.content ? ["", formatContent(item.content)] : []),
+                    ...(item.resources?.length
+                        ? ["", `Links (${item.resources.length}):`, ...item.resources.map((r) => `  [${r.id}] ${compactText(r.label)} — ${r.url}`), "", `Download one: wilma news ${item.wilmaId} download <resource>`]
+                        : []),
+                ].join("\n");
+            }
+            return perStudent(result, "news", (items) => {
+                const lines = items.length ? items.map((n) => `  ${newsLine(n)}`) : ["  No bulletins."];
+                return lines;
+            });
+        }
+        case "printouts":
+            return perStudent(result, "printouts", (items) => items.length ? [...items.map((p) => `  ${compactText(p.title)} (id ${p.id})`)] : ["  No printouts."]);
+        case "students":
+            return result.students
+                .map((s) => `${s.studentNumber}  ${s.name}${s.wilma ? `  (${s.wilma})` : ""}`)
+                .join("\n");
+        default:
+            return JSON.stringify(result, null, 2);
+    }
+}