@wilm-ai/wilma-cli 1.5.2 → 1.6.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Wilm.ai
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -60,10 +60,13 @@ wilma grades list [--limit 20] [--student <id|name>] [--all-students] [--json]
 ```bash
 wilma news list [--limit 20] [--student <id|name>] [--all-students] [--json]
 wilma news read <id> [--student <id|name>] [--json]
+wilma news resource download <news-id> <resource-id> [--student <id|name>] [--output <directory>] [--json]
 wilma messages list [--folder inbox] [--limit 20] [--student <id|name>] [--all-students] [--json]
 wilma messages read <id> [--student <id|name>] [--json]
 ```
 
+`news read --json` includes a `resources` array with every link in the bulletin. Any resource can be passed to the download command (the resource id also accepts a bare number, e.g. `1` for `resource-1`). Wilma-hosted files download through the authenticated session; external URLs are fetched with an isolated, unauthenticated request — no Wilma credentials are ever sent to external hosts. The result `status` reports what actually happened: `downloaded` (use the returned `path`), or `not_a_file` when the URL answered with a web page instead of a file (for example a sharing link that requires signing in — open it in a browser instead). `--output` defaults to the current directory; existing files are never overwritten.
+
 ### Attendance / lesson notes
 ```bash
 wilma attendance list [--date YYYY-MM-DD] [--student <id|name>] [--all-students] [--json]

package/dist/index.js

@@ -2,8 +2,9 @@
 import { emitKeypressEvents } from "node:readline";
 import { select, input, password } from "@inquirer/prompts";
 import { createHmac } from "node:crypto";
-import { readFile, writeFile, mkdir } from "node:fs/promises";
+import { readFile, writeFile, mkdir, open, rm } from "node:fs/promises";
 import { spawn } from "node:child_process";
+import { homedir } from "node:os";
 import { dirname, resolve } from "node:path";
 import { WilmaClient, MfaRequiredError, listTenants, } from "@wilm-ai/wilma-client";
 import { clearConfig, getConfigPath, loadConfig, obfuscateSecret, revealSecret, saveConfig, } from "./config.js";
@@ -373,7 +374,7 @@ async function chooseStudentFromProfile(stored, baseProfile, onMfa) {
     return students.find((s) => s.studentNumber === selected) ?? null;
 }
 async function handleCommand(args, config) {
-    const { command, subcommand, flags } = parseArgs(args);
+    const { command, subcommand, resourceAction, flags } = parseArgs(args);
     if (command === "config" && subcommand === "clear") {
         await clearConfig();
         console.log(`Cleared config at ${getConfigPath()}`);
@@ -405,6 +406,38 @@ async function handleCommand(args, config) {
         return;
     }
     if (command === "news") {
+        if (subcommand === "resource") {
+            if (resourceAction !== "download") {
+                throw new Error('Expected "wilma news resource download <news-id> <resource-id>"');
+            }
+            const newsId = parseReadId(flags.id, "news");
+            const resourceId = normalizeResourceId(flags.resourceId);
+            if (!resourceId) {
+                throw new Error("Missing news resource id (for example, resource-1 or just 1)");
+            }
+            if (!flags.student) {
+                const students = await getStudentsForCommand(profile, config);
+                if (students.length > 1) {
+                    console.error("Multiple students found. Use --student <id> to specify which one:");
+                    students.forEach((s) => console.error(`  ${s.studentNumber}  ${s.name}`));
+                    process.exit(1);
+                }
+            }
+            const studentInfo = await resolveStudentForFlags(profile, config, flags.student);
+            if (!studentInfo && !profile.studentNumber) {
+                await printStudentSelectionHelp(profile, config);
+                return;
+            }
+            const perStudentClient = await WilmaClient.login({
+                ...profile,
+                studentNumber: studentInfo?.studentNumber ?? profile.studentNumber,
+            }, mfaCallback);
+            await outputNewsResourceDownload(perStudentClient, newsId, resourceId, {
+                output: flags.output,
+                json: flags.json,
+            });
+            return;
+        }
         if (subcommand === "read" && flags.id) {
             const newsId = parseReadId(flags.id, "news");
             if (!flags.student) {
@@ -424,7 +457,9 @@ async function handleCommand(args, config) {
                 ...profile,
                 studentNumber: studentInfo?.studentNumber ?? profile.studentNumber,
             }, mfaCallback);
-            await outputNewsItem(perStudentClient, newsId, flags.json);
+            await outputNewsItem(perStudentClient, newsId, flags.json, {
+                studentNumber: studentInfo?.studentNumber ?? profile.studentNumber,
+            });
             return;
         }
         if (flags.allStudents) {
@@ -635,6 +670,7 @@ function printUsage() {
     console.log("  wilma kids list [--json]");
     console.log("  wilma news list [--limit 20] [--student <id|name>] [--all-students] [--json]");
     console.log("  wilma news read <id> [--student <id|name>] [--json]");
+    console.log("  wilma news resource download <news-id> <resource-id> [--student <id|name>] [--output <directory>] [--json]");
     console.log("  wilma messages list [--folder inbox] [--limit 20] [--student <id|name>] [--all-students] [--json]");
     console.log("  wilma messages read <id> [--student <id|name>] [--json]");
     console.log("  wilma attendance list [--date YYYY-MM-DD] [--student <id|name>] [--all-students] [--json]");
@@ -674,6 +710,7 @@ function parseArgs(args) {
     const subcommand = rawSubcommand?.startsWith("--") ? undefined : rawSubcommand;
     const rest = rawSubcommand?.startsWith("--") ? [rawSubcommand, ...rawRest] : rawRest;
     const flags = {};
+    const positionals = [];
     let i = 0;
     while (i < rest.length) {
         const arg = rest[i];
@@ -738,14 +775,27 @@ function parseArgs(args) {
             i += 2;
             continue;
         }
-        if (!flags.id && !arg.startsWith("--")) {
-            flags.id = arg;
-            i += 1;
+        if (arg === "--output") {
+            flags.output = rest[i + 1];
+            i += 2;
             continue;
         }
+        if (!arg.startsWith("--")) {
+            positionals.push(arg);
+        }
         i += 1;
     }
-    return { command, subcommand, flags };
+    const resourceAction = command === "news" && subcommand === "resource"
+        ? positionals[0]
+        : undefined;
+    if (resourceAction) {
+        flags.id = positionals[1];
+        flags.resourceId = positionals[2];
+    }
+    else {
+        flags.id = positionals[0];
+    }
+    return { command, subcommand, resourceAction, flags };
 }
 function parseReadId(raw, entity) {
     if (!raw) {
@@ -952,11 +1002,11 @@ async function outputNews(client, opts) {
         console.log(`- ${prefix}${date} ${compactText(item.title)} (id:${item.wilmaId})`.trim());
     });
 }
-async function outputNewsItem(client, id, json) {
+async function outputNewsItem(client, id, json, opts) {
     const item = await client.news.get(id);
     if (json) {
         console.log(JSON.stringify(item, null, 2));
-        return;
+        return item;
     }
     console.log(`\n${item.title}`);
     if (item.subtitle)
@@ -965,6 +1015,172 @@ async function outputNewsItem(client, id, json) {
         console.log(item.published.toISOString());
     if (item.content)
         console.log(`\n${formatContent(item.content)}`);
+    if (item.resources?.length) {
+        console.log(`\nResources (${item.resources.length})`);
+        for (const resource of item.resources) {
+            const origin = resource.authContext === "wilma" ? "Wilma" : new URL(resource.url).host;
+            console.log(`\n[${resource.id}] ${resource.label} (${origin})`);
+            console.log(`    ${resource.url}`);
+        }
+        if (!opts?.suppressDownloadHint) {
+            const student = opts?.studentNumber ?? "<id|name>";
+            console.log(`\nDownload any resource with:\n  wilma news resource download ${item.wilmaId} <resource-id> --student ${student} --output <directory>`);
+        }
+    }
+    return item;
+}
+const MAX_NEWS_RESOURCE_BYTES = 50 * 1024 * 1024;
+async function outputNewsResourceDownload(client, newsId, resourceId, opts) {
+    const item = await client.news.get(newsId);
+    const resource = item.resources?.find((candidate) => candidate.id === resourceId);
+    if (!resource) {
+        const known = (item.resources ?? []).map((r) => r.id).join(", ") || "none";
+        throw new Error(`News resource "${resourceId}" not found in news item ${newsId} (available: ${known})`);
+    }
+    const fetched = await client.news.fetchResource(newsId, resourceId, { item });
+    if (fetched.status === "not_a_file" || !fetched.response) {
+        const result = {
+            status: "not_a_file",
+            newsId,
+            resource,
+            availableActions: ["open_in_browser"],
+            message: "The link answered with a web page instead of a file. It may require signing in — open the URL in a browser instead.",
+        };
+        if (opts.json) {
+            console.log(JSON.stringify(result, null, 2));
+        }
+        else {
+            console.log(`\n${resource.label}`);
+            console.log(result.message);
+            console.log(resource.url);
+        }
+        return result;
+    }
+    const { response } = fetched;
+    if (!response.ok) {
+        await response.body?.cancel();
+        throw new Error(`News resource download failed with HTTP ${response.status}`);
+    }
+    const contentType = response.headers.get("content-type")?.split(";", 1)[0]?.trim() || null;
+    const declaredLength = Number(response.headers.get("content-length") ?? "0");
+    if (Number.isFinite(declaredLength) && declaredLength > MAX_NEWS_RESOURCE_BYTES) {
+        await response.body?.cancel();
+        throw new Error("News resource exceeds the 50 MB download limit");
+    }
+    const outputDirectory = resolve(opts.output ?? process.cwd());
+    await mkdir(outputDirectory, { recursive: true });
+    const preferredName = fileNameFromResponse(resource, response.headers.get("content-disposition"), contentType);
+    const { path, handle } = await createUniqueDownloadFile(outputDirectory, preferredName);
+    let sizeBytes = 0;
+    try {
+        if (!response.body) {
+            throw new Error("News resource response had no body");
+        }
+        const reader = response.body.getReader();
+        while (true) {
+            const { done, value } = await reader.read();
+            if (done)
+                break;
+            sizeBytes += value.byteLength;
+            if (sizeBytes > MAX_NEWS_RESOURCE_BYTES) {
+                await reader.cancel();
+                throw new Error("News resource exceeds the 50 MB download limit");
+            }
+            let offset = 0;
+            while (offset < value.byteLength) {
+                const { bytesWritten } = await handle.write(value, offset, value.byteLength - offset);
+                if (bytesWritten === 0) {
+                    throw new Error("Could not write news resource to disk");
+                }
+                offset += bytesWritten;
+            }
+        }
+        await handle.close();
+    }
+    catch (error) {
+        await handle.close().catch(() => undefined);
+        await rm(path, { force: true });
+        throw error;
+    }
+    const result = {
+        status: "downloaded",
+        newsId,
+        resourceId,
+        path,
+        contentType,
+        sizeBytes,
+    };
+    if (opts.json) {
+        console.log(JSON.stringify(result, null, 2));
+    }
+    else {
+        console.log(`Downloaded ${resource.label} to ${path}`);
+    }
+    return result;
+}
+function normalizeResourceId(raw) {
+    if (!raw)
+        return undefined;
+    return /^\d+$/.test(raw) ? `resource-${raw}` : raw;
+}
+function fileNameFromResponse(resource, contentDisposition, contentType) {
+    const encoded = /filename\*=UTF-8''([^;]+)/i.exec(contentDisposition ?? "")?.[1];
+    const quoted = /filename="([^"]+)"/i.exec(contentDisposition ?? "")?.[1];
+    const plain = /filename=([^;]+)/i.exec(contentDisposition ?? "")?.[1]?.trim();
+    let name = encoded ? decodeURIComponentSafely(encoded) : quoted ?? plain ?? resource.fileName ?? resource.label;
+    name = sanitizeFileName(name);
+    if (!/\.[A-Za-z0-9]{1,8}$/.test(name)) {
+        const extension = extensionForContentType(contentType);
+        if (extension)
+            name += extension;
+    }
+    return name || "wilma-resource";
+}
+function sanitizeFileName(value) {
+    return value
+        .replace(/[\\/:*?"<>|\u0000-\u001f]/g, "_")
+        .replace(/^\.+|\.+$/g, "")
+        .trim()
+        .slice(0, 180);
+}
+function extensionForContentType(contentType) {
+    const extensions = {
+        "application/pdf": ".pdf",
+        "application/zip": ".zip",
+        "image/jpeg": ".jpg",
+        "image/png": ".png",
+        "text/plain": ".txt",
+        "text/csv": ".csv",
+    };
+    return contentType ? extensions[contentType] ?? "" : "";
+}
+function decodeURIComponentSafely(value) {
+    try {
+        return decodeURIComponent(value);
+    }
+    catch {
+        return value;
+    }
+}
+async function createUniqueDownloadFile(directory, preferredName) {
+    const dot = preferredName.lastIndexOf(".");
+    const hasExtension = dot > 0;
+    const stem = hasExtension ? preferredName.slice(0, dot) : preferredName;
+    const extension = hasExtension ? preferredName.slice(dot) : "";
+    for (let index = 0; index < 1000; index += 1) {
+        const candidate = index === 0 ? preferredName : `${stem}-${index}${extension}`;
+        const path = resolve(directory, candidate);
+        try {
+            const handle = await open(path, "wx", 0o600);
+            return { path, handle };
+        }
+        catch (error) {
+            if (error.code !== "EEXIST") {
+                throw error;
+            }
+        }
+    }
+    throw new Error("Could not choose a unique output filename");
 }
 async function outputExams(client, opts) {
     const exams = await client.exams.list();
@@ -1298,7 +1514,40 @@ async function selectNewsToRead(client) {
     });
     if (!selected || selected === "back")
         return;
-    await outputNewsItem(client, Number(selected), false);
+    const item = await outputNewsItem(client, Number(selected), false, { suppressDownloadHint: true });
+    if (item?.resources?.length) {
+        await offerResourceDownloads(client, item);
+    }
+}
+async function offerResourceDownloads(client, item) {
+    while (true) {
+        const resources = item.resources ?? [];
+        const choices = [
+            { value: "back", name: "Continue" },
+            ...resources.map((resource) => ({
+                value: resource.id,
+                name: `Download "${compactText(resource.label)}"`,
+            })),
+        ];
+        const selected = await selectOrCancel({ message: "Resources", choices }, false);
+        if (!selected || selected === "back")
+            return;
+        const outputDirectory = await inputOrCancel({
+            message: "Save to directory",
+            default: resolve(homedir(), "Downloads"),
+        });
+        if (outputDirectory === null)
+            continue;
+        try {
+            await outputNewsResourceDownload(client, item.wilmaId, selected, {
+                output: outputDirectory,
+                json: false,
+            });
+        }
+        catch (error) {
+            console.error("Download failed:", error instanceof Error ? error.message : error);
+        }
+    }
 }
 async function selectMessageToRead(client, folder) {
     const messages = await client.messages.list(folder);
@@ -1758,6 +2007,12 @@ main().catch((err) => {
         console.error("For interactive use, run 'wilma' without arguments.");
         process.exit(1);
     }
-    console.error("CLI error:", err instanceof Error ? err.message : err);
+    const message = err instanceof Error ? err.message : String(err);
+    if (process.argv.includes("--json")) {
+        console.log(JSON.stringify({ status: "error", message }, null, 2));
+    }
+    else {
+        console.error("CLI error:", message);
+    }
     process.exit(1);
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wilm-ai/wilma-cli",
-  "version": "1.5.2",
+  "version": "1.6.0",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -8,17 +8,9 @@
     "wilmai": "dist/index.js",
     "wilma": "dist/index.js"
   },
-  "scripts": {
-    "build": "tsc -p tsconfig.json",
-    "lint": "echo 'add lint'",
-    "test": "echo 'add tests'",
-    "start": "node dist/index.js",
-    "prepack": "pnpm --filter @wilm-ai/wilma-client build && pnpm --filter @wilm-ai/wilma-cli build",
-    "test:live": "tsc -p tsconfig.json && node test/live.spec.mjs"
-  },
   "dependencies": {
     "@inquirer/prompts": "^5.3.8",
-    "@wilm-ai/wilma-client": "workspace:^"
+    "@wilm-ai/wilma-client": "^1.5.0"
   },
   "devDependencies": {
     "typescript": "^5.6.3"
@@ -29,5 +21,12 @@
   ],
   "publishConfig": {
     "access": "public"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "lint": "echo 'add lint'",
+    "test": "pnpm --filter @wilm-ai/wilma-client build && pnpm run build && node test/news-resources.mjs",
+    "start": "node dist/index.js",
+    "test:live": "tsc -p tsconfig.json && node test/live.spec.mjs"
   }
-}
+}