moodle-cli 0.5.5 → 0.6.0

package/dist/moodle.js

@@ -2,7 +2,7 @@
 
 // src/cli.ts
 import { Command, CommanderError } from "commander";
-import { realpathSync } from "fs";
+import { realpathSync as realpathSync2 } from "fs";
 import { fileURLToPath } from "url";
 
 // src/client.ts
@@ -36,11 +36,16 @@ var FUNC_GET_POPUP_NOTIFICATIONS = "message_popup_get_popup_notifications";
 var FUNC_GET_CONVERSATION_COUNTS = "core_message_get_conversation_counts";
 var FUNC_GET_UNREAD_CONVERSATION_COUNTS = "core_message_get_unread_conversation_counts";
 var FUNC_GET_DISCUSSION_POSTS = "mod_forum_get_discussion_posts";
+var FUNC_SESSION_TOUCH = "core_session_touch";
+var FUNC_SESSION_TIME_REMAINING = "core_session_time_remaining";
 var CONFIG_FILENAME = "config.yaml";
 var CONFIG_DIR_NAME = ".config/moodle-cli";
 var CACHE_DIR_NAME = ".cache/moodle-cli";
 var SESSION_CACHE_FILENAME = "session.json";
-var DEFAULT_SESSION_CACHE_TTL_MS = 2 * 60 * 60 * 1e3;
+var DEFAULT_SESSION_CACHE_TTL_MS = 24 * 60 * 60 * 1e3;
+var KEEPALIVE_LAUNCH_AGENT_LABEL = "com.moodle-cli.keepalive";
+var KEEPALIVE_DEFAULT_INTERVAL_MINUTES = 30;
+var KEEPALIVE_LOG_FILENAME = "keepalive.log";
 var ENV_MOODLE_SESSION = "MOODLE_SESSION";
 var ENV_MOODLE_BASE_URL = "MOODLE_BASE_URL";
 var MOODLE_SESSION_COOKIE_PREFIX = "MoodleSession";
@@ -236,7 +241,7 @@ async function getAuthenticatedSession(baseUrl, options = {}) {
     await refreshSessionCache(baseUrl, oktaSession.cookie, oktaSession.context, options);
     return { baseUrl, cookie: oktaSession.cookie, ...oktaSession.context, fromCache: false };
   }
-  if (!options.oktaCookieProvider && oktaCookies.length) {
+  if (!options.oktaCookieProvider && oktaCookies.length && !options.nonInteractive) {
     const refreshed = matchingMoodleSessionCookies(
       await loadSessionsFromOktaCli(baseUrl, { ...options, oktaCookieProvider: void 0, noCache: true }, true),
       baseUrl
@@ -286,7 +291,7 @@ async function loadSessionsFromOktaCli(baseUrl, options = {}, forceLogin = false
     return [];
   }
   const stored = await readOktaCookies(executable, baseUrl, execFile);
-  if (stored.length && !forceLogin) {
+  if (stored.length && !forceLogin || options.nonInteractive) {
     return stored;
   }
   const login = await runOktaJson(executable, ["login", baseUrl], execFile);
@@ -304,6 +309,9 @@ function authFailureHint(baseUrl) {
     `okta-auth: ${OKTA_AUTH_URL}`
   ].join("\n");
 }
+async function invalidateCachedSession(baseUrl, options = {}) {
+  await deleteCachedSession(baseUrl, cacheOptions(options));
+}
 function parseSessionContext(html) {
   const sesskey = firstMatch(html, [
     /"sesskey"\s*:\s*"([^"]+)"/,
@@ -630,6 +638,75 @@ function isRecord2(value) {
   return !!value && typeof value === "object" && !Array.isArray(value);
 }
 
+// src/html-utils.ts
+import { parse } from "node-html-parser";
+function htmlToStructuredContent(html, baseUrl) {
+  if (!html) {
+    return { text: "", image_urls: [], links: [], tables: [] };
+  }
+  const root = parse(html);
+  const image_urls = [];
+  const links = [];
+  const tables = [];
+  for (const br of root.querySelectorAll("br")) {
+    br.replaceWith("\n");
+  }
+  for (const img of root.querySelectorAll("img")) {
+    const src = (img.getAttribute("src") ?? "").trim();
+    if (!src) {
+      img.replaceWith("[image]");
+      continue;
+    }
+    const absolute = resolveUrl(baseUrl, src);
+    image_urls.push(absolute);
+    const label = (img.getAttribute("alt") ?? "").trim() || "image";
+    img.replaceWith(`[${label}] ${absolute}`);
+  }
+  for (const link of root.querySelectorAll("a[href]")) {
+    const href = (link.getAttribute("href") ?? "").trim();
+    if (!href) {
+      continue;
+    }
+    links.push({ text: cleanText(link.textContent), url: resolveUrl(baseUrl, href) });
+  }
+  for (const table of root.querySelectorAll("table")) {
+    const headers = [];
+    const rows = [];
+    for (const row of table.querySelectorAll("tr")) {
+      const headerCells = row.querySelectorAll("th");
+      const dataCells = row.querySelectorAll("td");
+      const cells = headerCells.length ? headerCells : dataCells;
+      if (!cells.length) {
+        continue;
+      }
+      const values = cells.map((cell) => cleanText(cell.textContent));
+      if (headerCells.length && !headers.length && !rows.length) {
+        headers.push(...values);
+      } else {
+        rows.push(values);
+      }
+    }
+    if (headers.length || rows.length) {
+      tables.push({ headers, rows });
+    }
+  }
+  const text = root.textContent.split(/\r?\n/).map((line) => cleanText(line)).filter(Boolean).join("\n");
+  return { text, image_urls, links, tables };
+}
+function cleanText(value) {
+  return decodeHtml2(value ?? "").replace(/\s+/g, " ").trim();
+}
+function resolveUrl(baseUrl, href) {
+  try {
+    return new URL(href, baseUrl).toString();
+  } catch {
+    return href;
+  }
+}
+function decodeHtml2(value) {
+  return value.replace(/&nbsp;/g, " ").replace(/&amp;/g, "&").replace(/&lt;/g, "<").replace(/&gt;/g, ">").replace(/&quot;/g, '"').replace(/&#39;/g, "'");
+}
+
 // src/parsers.ts
 function schema(parser) {
   return { parse: parser };
@@ -767,18 +844,20 @@ function parseForumPostAuthor(value) {
     profile_image_url: stringValue(urls.profileimage)
   };
 }
-function parseForumPost(value) {
+function parseForumPost(value, baseUrl = "") {
   const data = asRecord(value);
   const urls = asRecord(data.urls);
+  const messageHtml = stringValue(data.message);
+  const structured = htmlToStructuredContent(messageHtml, stringValue(urls.view || urls.discuss) || baseUrl);
   return {
     id: numberValue(data.id),
     discussion_id: numberValue(data.discussionid),
     subject: stringValue(data.subject),
-    message_html: stringValue(data.message),
-    message_text: stringValue(data.message).replace(/<[^>]+>/g, " ").replace(/\s+/g, " ").trim(),
-    image_urls: [],
-    links: [],
-    tables: [],
+    message_html: messageHtml,
+    message_text: structured.text,
+    image_urls: structured.image_urls,
+    links: structured.links,
+    tables: structured.tables,
     author: parseForumPostAuthor(data.author),
     parent_id: numberValue(data.parentid),
     time_created: numberValue(data.timecreated),
@@ -791,9 +870,9 @@ function parseForumPost(value) {
     reply_url: stringValue(urls.reply)
   };
 }
-function parseForumDiscussion(value, discussionId) {
+function parseForumDiscussion(value, discussionId, baseUrl = "") {
   const data = asRecord(value);
-  const posts = asArray(data.posts).map((item) => parseForumPost(item));
+  const posts = asArray(data.posts).map((item) => parseForumPost(item, baseUrl));
   return {
     id: discussionId,
     subject: posts[0]?.subject ?? "",
@@ -832,77 +911,6 @@ function booleanValue(value, defaultValue = false) {
 
 // src/scraper.ts
 import { parse as parse2 } from "node-html-parser";
-
-// src/html-utils.ts
-import { parse } from "node-html-parser";
-function htmlToStructuredContent(html, baseUrl) {
-  if (!html) {
-    return { text: "", image_urls: [], links: [], tables: [] };
-  }
-  const root = parse(html);
-  const image_urls = [];
-  const links = [];
-  const tables = [];
-  for (const br of root.querySelectorAll("br")) {
-    br.replaceWith("\n");
-  }
-  for (const img of root.querySelectorAll("img")) {
-    const src = (img.getAttribute("src") ?? "").trim();
-    if (!src) {
-      img.replaceWith("[image]");
-      continue;
-    }
-    const absolute = resolveUrl(baseUrl, src);
-    image_urls.push(absolute);
-    const label = (img.getAttribute("alt") ?? "").trim() || "image";
-    img.replaceWith(`[${label}] ${absolute}`);
-  }
-  for (const link of root.querySelectorAll("a[href]")) {
-    const href = (link.getAttribute("href") ?? "").trim();
-    if (!href) {
-      continue;
-    }
-    links.push({ text: cleanText(link.textContent), url: resolveUrl(baseUrl, href) });
-  }
-  for (const table of root.querySelectorAll("table")) {
-    const headers = [];
-    const rows = [];
-    for (const row of table.querySelectorAll("tr")) {
-      const headerCells = row.querySelectorAll("th");
-      const dataCells = row.querySelectorAll("td");
-      const cells = headerCells.length ? headerCells : dataCells;
-      if (!cells.length) {
-        continue;
-      }
-      const values = cells.map((cell) => cleanText(cell.textContent));
-      if (headerCells.length && !headers.length && !rows.length) {
-        headers.push(...values);
-      } else {
-        rows.push(values);
-      }
-    }
-    if (headers.length || rows.length) {
-      tables.push({ headers, rows });
-    }
-  }
-  const text = root.textContent.split(/\r?\n/).map((line) => cleanText(line)).filter(Boolean).join("\n");
-  return { text, image_urls, links, tables };
-}
-function cleanText(value) {
-  return decodeHtml2(value ?? "").replace(/\s+/g, " ").trim();
-}
-function resolveUrl(baseUrl, href) {
-  try {
-    return new URL(href, baseUrl).toString();
-  } catch {
-    return href;
-  }
-}
-function decodeHtml2(value) {
-  return value.replace(/&nbsp;/g, " ").replace(/&amp;/g, "&").replace(/&lt;/g, "<").replace(/&gt;/g, ">").replace(/&quot;/g, '"').replace(/&#39;/g, "'");
-}
-
-// src/scraper.ts
 function parsePageContext(html, baseUrl) {
   const root = parse2(html);
   const config = parseMoodleConfig(html);
@@ -1422,33 +1430,453 @@ function cleanTableCell(node) {
   if (!node) {
     return "";
   }
-  const clone = parse2(node.toString());
-  for (const unwanted of clone.querySelectorAll(".action-menu, .dropdown, script, style")) {
-    unwanted.remove();
+  const clone = parse2(node.toString());
+  for (const unwanted of clone.querySelectorAll(".action-menu, .dropdown, script, style")) {
+    unwanted.remove();
+  }
+  return cleanText(clone.textContent.replace("( Empty )", "(Empty)"));
+}
+function numberQueryValue(href, key) {
+  try {
+    return numericQueryValue(new URL(href, "https://moodle.invalid"), key);
+  } catch {
+    return null;
+  }
+}
+function numberValue2(value) {
+  if (typeof value === "number" && Number.isFinite(value)) {
+    return value;
+  }
+  if (typeof value === "string" && value.trim() !== "" && Number.isFinite(Number(value))) {
+    return Number(value);
+  }
+  return 0;
+}
+function stringValue2(value) {
+  return typeof value === "string" ? value : value == null ? "" : String(value);
+}
+function unique(items) {
+  return [...new Set(items)];
+}
+
+// src/forum.ts
+var ForumModule = class {
+  baseUrl;
+  callMoodle;
+  loadPage;
+  loadCourses;
+  loadCourseContents;
+  forumDiscussionCache = /* @__PURE__ */ new Map();
+  forumDiscussionRefsCache = /* @__PURE__ */ new Map();
+  constructor(options) {
+    this.baseUrl = options.baseUrl.replace(/\/$/, "");
+    this.callMoodle = options.call;
+    this.loadPage = options.getPage;
+    this.loadCourses = options.getCourses;
+    this.loadCourseContents = options.getCourseContents;
+  }
+  async getForumDiscussion(discussionId) {
+    const cached = this.forumDiscussionCache.get(discussionId);
+    if (cached) {
+      return cached;
+    }
+    try {
+      const data = await this.callMoodle(FUNC_GET_DISCUSSION_POSTS, {
+        discussionid: discussionId,
+        sortby: "created",
+        sortdirection: "ASC",
+        includeinlineattachments: true
+      });
+      const discussion2 = parseForumDiscussion(data, discussionId, this.baseUrl);
+      if (discussion2.group_id <= 0) {
+        const html2 = await this.loadPage(FORUM_DISCUSS_PATH, { d: discussionId }).catch(() => "");
+        if (html2) {
+          const [groupId, groupName] = parseForumDiscussionGroupHtml(html2);
+          discussion2.group_id = groupId;
+          discussion2.group_name = groupName;
+        }
+      }
+      this.forumDiscussionCache.set(discussionId, discussion2);
+      return discussion2;
+    } catch (error) {
+      if (!shouldFallbackForumAjax(error)) {
+        throw error;
+      }
+    }
+    const html = await this.loadPage(FORUM_DISCUSS_PATH, { d: discussionId });
+    const discussion = parseForumDiscussionHtml(html, this.baseUrl, discussionId);
+    this.forumDiscussionCache.set(discussionId, discussion);
+    return discussion;
+  }
+  async getForumViewCmid(discussionId) {
+    const html = await this.loadPage(FORUM_DISCUSS_PATH, { d: discussionId });
+    return parseForumViewCmidFromDiscussionHtml(html);
+  }
+  async getForumDiscussionRefs(forumCmid) {
+    const cached = this.forumDiscussionRefsCache.get(forumCmid);
+    if (cached) {
+      return cached;
+    }
+    const html = await this.loadPage(FORUM_VIEW_PATH, { id: forumCmid });
+    const groups = parseForumGroupsHtml(html);
+    const refs = groups.length ? [] : parseForumDiscussionRefsHtml(html, this.baseUrl);
+    const seenIds = new Set(refs.map((ref) => ref.id));
+    for (const [groupId, groupName] of groups) {
+      const groupHtml = await this.loadPage(FORUM_VIEW_PATH, { id: forumCmid, group: groupId });
+      for (const ref of parseForumDiscussionRefsHtml(groupHtml, this.baseUrl)) {
+        if (seenIds.has(ref.id)) {
+          continue;
+        }
+        seenIds.add(ref.id);
+        refs.push({ ...ref, group_id: groupId, group_name: groupName });
+      }
+    }
+    this.forumDiscussionRefsCache.set(forumCmid, refs);
+    return refs;
+  }
+  async getCourseForums(courseId, courseName = "") {
+    if (!this.loadCourseContents) {
+      throw new Error("getCourseContents loader is required to list course forums");
+    }
+    const sections = await this.loadCourseContents(courseId);
+    return sections.flatMap(
+      (section) => section.activities.filter((activity) => activity.modname === "forum").map((activity) => ({
+        id: activity.id,
+        name: activity.name,
+        course_id: courseId,
+        course_name: courseName,
+        url: activity.url
+      }))
+    );
+  }
+  async getForums(courseId) {
+    if (courseId !== void 0) {
+      const courseName = await this.courseName(courseId);
+      return this.getCourseForums(courseId, courseName);
+    }
+    if (!this.loadCourses) {
+      throw new Error("getCourses loader is required to list all forums");
+    }
+    const forums = [];
+    for (const course of await this.loadCourses()) {
+      forums.push(...await this.getCourseForums(course.id, course.fullname || course.shortname));
+    }
+    return forums;
+  }
+  async courseName(courseId) {
+    if (!this.loadCourses) {
+      return "";
+    }
+    const course = (await this.loadCourses()).find((item) => item.id === courseId);
+    return course ? course.fullname || course.shortname : "";
+  }
+};
+function parseDiscussionReference(value) {
+  const raw = value.trim();
+  if (/^\d+$/.test(raw)) {
+    return { discussionId: Number(raw), postId: null };
+  }
+  let url;
+  try {
+    url = new URL(raw);
+  } catch {
+    throw new UsageError("DISCUSSION must be a numeric ID or a full discuss.php URL.");
+  }
+  const discussionValue = url.searchParams.get("d");
+  if (!discussionValue || !/^\d+$/.test(discussionValue)) {
+    throw new UsageError("Could not find discussion ID in URL query (expected ?d=...).");
+  }
+  const fragment = url.hash.replace(/^#/, "");
+  const postId = /^p\d+$/.test(fragment) ? Number(fragment.slice(1)) : null;
+  return { discussionId: Number(discussionValue), postId };
+}
+async function parseForumReference(value, resolveForumCmid) {
+  const raw = value.trim();
+  if (/^\d+$/.test(raw)) {
+    return Number(raw);
+  }
+  let url;
+  try {
+    url = new URL(raw);
+  } catch {
+    throw new UsageError("FORUM must be a numeric ID or a full forum URL.");
+  }
+  if (url.pathname.endsWith("/mod/forum/view.php")) {
+    const forumValue = url.searchParams.get("id");
+    if (!forumValue || !/^\d+$/.test(forumValue)) {
+      throw new UsageError("Could not find forum module ID in view.php URL (expected ?id=...).");
+    }
+    return Number(forumValue);
+  }
+  if (url.pathname.endsWith("/mod/forum/discuss.php")) {
+    const discussionValue = url.searchParams.get("d");
+    if (!discussionValue || !/^\d+$/.test(discussionValue)) {
+      throw new UsageError("Could not find discussion ID in discuss.php URL (expected ?d=...).");
+    }
+    if (!resolveForumCmid) {
+      throw new UsageError("A discuss.php URL needs a resolver to find the forum ID.");
+    }
+    const forumCmid = await resolveForumCmid(Number(discussionValue));
+    if (!forumCmid) {
+      throw new NotFoundError("Could not resolve forum ID from the discussion page.");
+    }
+    return forumCmid;
+  }
+  throw new UsageError("Unsupported forum URL. Use a view.php?id=... or discuss.php?d=... URL.");
+}
+function filterDiscussionToPost(discussion, postId) {
+  if (postId == null) {
+    return discussion;
+  }
+  const posts = discussion.posts.filter((post) => post.id === postId);
+  if (!posts.length) {
+    throw new NotFoundError(`Post ${postId} was not found in discussion ${discussion.id}.`);
+  }
+  return { ...discussion, posts };
+}
+function shouldFallbackForumAjax(error) {
+  if (!(error instanceof MoodleAPIError)) {
+    return false;
+  }
+  return error.moodleErrorCode === "servicenotavailable" || error.moodleErrorCode === "accessexception" || error.message.includes("Web service is not available");
+}
+
+// src/forum-search.ts
+async function searchForumContent(source, query, options = {}) {
+  const cleanedQuery = query.trim();
+  if (!cleanedQuery) {
+    return [];
+  }
+  const includePostText = options.includePostText ?? true;
+  const unreadOnly = options.unreadOnly ?? false;
+  const sortBy = options.sortBy ?? "relevance";
+  let forumRefs = await source.getForums(options.courseId);
+  if (options.forumCmid !== void 0) {
+    forumRefs = forumRefs.filter((ref) => ref.id === options.forumCmid);
+    if (!forumRefs.length) {
+      forumRefs = [
+        {
+          id: options.forumCmid,
+          name: "",
+          course_id: 0,
+          course_name: "",
+          url: `${(options.baseUrl ?? "").replace(/\/$/, "")}/mod/forum/view.php?id=${options.forumCmid}`
+        }
+      ];
+    }
+  } else if (options.maxForums !== void 0) {
+    forumRefs = forumRefs.slice(0, options.maxForums);
+  }
+  const hits = [];
+  const seen = /* @__PURE__ */ new Set();
+  for (const forumRef of forumRefs) {
+    let refs = await source.getForumDiscussionRefs(forumRef.id);
+    if (options.maxDiscussionsPerForum !== void 0) {
+      refs = refs.slice(0, options.maxDiscussionsPerForum);
+    }
+    for (const ref of refs) {
+      let discussion = null;
+      let latestPost = null;
+      let discussionHasUnread = false;
+      const matchingPostHits = [];
+      if (includePostText || unreadOnly || sortBy === "recent") {
+        discussion = await source.getForumDiscussion(ref.id);
+        if (discussion.posts.length) {
+          latestPost = discussion.posts.reduce((latest, post) => (post.time_created || 0) > (latest.time_created || 0) ? post : latest);
+          discussionHasUnread = discussion.posts.some((post) => post.unread);
+        }
+      }
+      if (!includePostText) {
+        addSubjectHit({
+          hits,
+          seen,
+          score: matchScore(ref.subject, cleanedQuery),
+          query: cleanedQuery,
+          ref,
+          forumRef,
+          discussionHasUnread,
+          unreadOnly,
+          latestPost
+        });
+        continue;
+      }
+      discussion ??= await source.getForumDiscussion(ref.id);
+      for (const post of discussion.posts) {
+        const postSubjectScore = matchScore(post.subject, cleanedQuery);
+        const postBodyScore = matchScore(post.message_text, cleanedQuery);
+        if (postSubjectScore <= 0 && postBodyScore <= 0) {
+          continue;
+        }
+        if (unreadOnly && !post.unread) {
+          continue;
+        }
+        const matchedIn = postSubjectScore >= postBodyScore ? "post_subject" : "post_body";
+        const matchedText = matchedIn === "post_subject" ? post.subject : post.message_text;
+        matchingPostHits.push([
+          300 + Math.max(postSubjectScore, postBodyScore),
+          {
+            course_id: forumRef.course_id,
+            course_name: forumRef.course_name,
+            forum_id: forumRef.id,
+            forum_name: forumRef.name,
+            group_id: discussion.group_id || ref.group_id,
+            group_name: discussion.group_name || ref.group_name,
+            discussion_id: ref.id,
+            discussion_subject: discussion.subject || ref.subject,
+            post_id: post.id,
+            author_name: post.author.fullname,
+            matched_in: matchedIn,
+            snippet: snippetForText(matchedText, cleanedQuery),
+            unread: post.unread,
+            time_created: post.time_created,
+            url: post.url || ref.url
+          }
+        ]);
+      }
+      if (matchingPostHits.length) {
+        for (const [score, hit] of matchingPostHits) {
+          const key = hitKey(hit.discussion_id, hit.post_id);
+          if (seen.has(key)) {
+            continue;
+          }
+          seen.add(key);
+          hits.push([score, hit]);
+        }
+        continue;
+      }
+      addSubjectHit({
+        hits,
+        seen,
+        score: matchScore(ref.subject, cleanedQuery),
+        query: cleanedQuery,
+        ref,
+        forumRef,
+        discussionHasUnread,
+        unreadOnly,
+        latestPost
+      });
+    }
+  }
+  hits.sort(sortBy === "recent" ? sortRecent : sortRelevant);
+  return hits.slice(0, options.limit ?? 20).map(([, hit]) => hit);
+}
+async function checkForumDiscussions(source, forumCmid, limit = 20) {
+  const refs = (await source.getForumDiscussionRefs(forumCmid)).slice(0, limit);
+  const results = [];
+  for (const ref of refs) {
+    try {
+      const discussion = await source.getForumDiscussion(ref.id);
+      results.push({
+        discussion_id: ref.id,
+        subject: ref.subject,
+        ok: true,
+        posts: discussion.posts.length,
+        images: discussion.posts.reduce((count, post) => count + post.image_urls.length, 0)
+      });
+    } catch (error) {
+      results.push({
+        discussion_id: ref.id,
+        subject: ref.subject,
+        ok: false,
+        error: error instanceof Error ? error.message : String(error)
+      });
+    }
+  }
+  return results;
+}
+function normalizeQuery(value) {
+  const normalized = value.toLowerCase().split(/\s+/).filter(Boolean).join(" ");
+  return { normalized, tokens: normalized ? normalized.split(/\s+/) : [] };
+}
+function matchScore(text, query) {
+  const haystack = text.toLowerCase().split(/\s+/).filter(Boolean).join(" ");
+  if (!haystack) {
+    return 0;
+  }
+  const { normalized, tokens } = normalizeQuery(query);
+  if (!normalized) {
+    return 0;
+  }
+  if (haystack.includes(normalized)) {
+    return 100 + normalized.length;
+  }
+  if (tokens.length && tokens.every((token) => haystack.includes(token))) {
+    return 60 + tokens.length;
+  }
+  return 0;
+}
+function snippetForText(text, query, maxLen = 120) {
+  const cleaned = text.split(/\s+/).filter(Boolean).join(" ");
+  if (!cleaned) {
+    return "";
+  }
+  const { normalized, tokens } = normalizeQuery(query);
+  const lower = cleaned.toLowerCase();
+  let start = normalized ? lower.indexOf(normalized) : -1;
+  if (start < 0) {
+    for (const token of tokens) {
+      start = lower.indexOf(token);
+      if (start >= 0) {
+        break;
+      }
+    }
+  }
+  if (start < 0 || cleaned.length <= maxLen) {
+    return cleaned.length <= maxLen ? cleaned : `${cleaned.slice(0, maxLen - 1)}\u2026`;
+  }
+  const half = Math.floor(maxLen / 2);
+  const left = Math.max(0, start - half);
+  const right = Math.min(cleaned.length, left + maxLen);
+  let snippet = cleaned.slice(left, right);
+  if (left > 0) {
+    snippet = `\u2026${snippet}`;
   }
-  return cleanText(clone.textContent.replace("( Empty )", "(Empty)"));
-}
-function numberQueryValue(href, key) {
-  try {
-    return numericQueryValue(new URL(href, "https://moodle.invalid"), key);
-  } catch {
-    return null;
+  if (right < cleaned.length) {
+    snippet = `${snippet}\u2026`;
   }
+  return snippet;
 }
-function numberValue2(value) {
-  if (typeof value === "number" && Number.isFinite(value)) {
-    return value;
+function addSubjectHit(args) {
+  if (args.score <= 0 || args.unreadOnly && !args.discussionHasUnread) {
+    return;
   }
-  if (typeof value === "string" && value.trim() !== "" && Number.isFinite(Number(value))) {
-    return Number(value);
+  const key = hitKey(args.ref.id, 0);
+  if (args.seen.has(key)) {
+    return;
   }
-  return 0;
+  args.seen.add(key);
+  args.hits.push([
+    400 + args.score,
+    {
+      course_id: args.forumRef.course_id,
+      course_name: args.forumRef.course_name,
+      forum_id: args.forumRef.id,
+      forum_name: args.forumRef.name,
+      group_id: args.ref.group_id,
+      group_name: args.ref.group_name,
+      discussion_id: args.ref.id,
+      discussion_subject: args.ref.subject,
+      post_id: 0,
+      author_name: "",
+      matched_in: "discussion_subject",
+      snippet: snippetForText(args.ref.subject, args.query),
+      unread: args.discussionHasUnread,
+      time_created: args.latestPost?.time_created ?? 0,
+      url: args.ref.url
+    }
+  ]);
 }
-function stringValue2(value) {
-  return typeof value === "string" ? value : value == null ? "" : String(value);
+function sortRecent(a, b) {
+  return (b[1].time_created || 0) - (a[1].time_created || 0) || b[0] - a[0] || compareText(a[1].course_name, b[1].course_name) || compareText(a[1].forum_name, b[1].forum_name) || a[1].discussion_id - b[1].discussion_id || a[1].post_id - b[1].post_id;
 }
-function unique(items) {
-  return [...new Set(items)];
+function sortRelevant(a, b) {
+  return b[0] - a[0] || compareText(a[1].course_name, b[1].course_name) || compareText(a[1].forum_name, b[1].forum_name) || a[1].discussion_id - b[1].discussion_id || a[1].post_id - b[1].post_id;
+}
+function compareText(a, b) {
+  return a.toLowerCase().localeCompare(b.toLowerCase());
+}
+function hitKey(discussionId, postId) {
+  return `${discussionId}:${postId}`;
 }
 
 // src/client.ts
@@ -1472,8 +1900,7 @@ var MoodleClient = class {
   cacheOptions;
   onLoginRequired;
   retryingLogin = false;
-  forumDiscussions = /* @__PURE__ */ new Map();
-  forumRefs = /* @__PURE__ */ new Map();
+  forum;
   constructor(baseUrl, options) {
     this.baseUrl = baseUrl.replace(/\/$/, "");
     const resolvedOptions = typeof options === "string" ? { cookie: { name: "MoodleSession", value: options } } : options;
@@ -1484,22 +1911,45 @@ var MoodleClient = class {
     this.userInfo = resolvedOptions.pageContext?.user_info ?? null;
     this.cacheOptions = resolvedOptions.cacheOptions;
     this.onLoginRequired = resolvedOptions.onLoginRequired;
+    this.forum = new ForumModule({
+      baseUrl: this.baseUrl,
+      call: async (functionName, args) => {
+        await this.ensureSession();
+        return this.call(functionName, args);
+      },
+      getPage: (path3, params) => this.get(path3, params),
+      getCourses: () => this.getCourses(),
+      getCourseContents: (courseId) => this.getCourseContents(courseId)
+    });
   }
   async getSiteInfo() {
     await this.ensureSession();
-    const data = await this.call(FUNC_GET_SITE_INFO);
-    if (!isRecord3(data) || !("userid" in data)) {
-      if (this.userInfo) {
-        return this.userInfo;
+    try {
+      const data = await this.call(FUNC_GET_SITE_INFO);
+      if (isRecord3(data) && "userid" in data) {
+        const info = parseUserInfo(data);
+        this.sesskey = typeof data.sesskey === "string" ? data.sesskey : this.sesskey;
+        this.userid = info.userid;
+        this.userInfo = info;
+        await this.writeCache();
+        return info;
+      }
+    } catch (error) {
+      if (!(error instanceof MoodleAPIError) || error.moodleErrorCode !== "servicenotavailable") {
+        throw error;
       }
-      throw new NotFoundError("Session appears invalid: could not retrieve user info");
     }
-    const info = parseUserInfo(data);
-    this.sesskey = typeof data.sesskey === "string" ? data.sesskey : this.sesskey;
-    this.userid = info.userid;
-    this.userInfo = info;
+    if (this.userInfo?.fullname) {
+      return this.userInfo;
+    }
+    const html = await this.get(DASHBOARD_PATH);
+    const context = parsePageContext(html, this.baseUrl);
+    if (!context.user_info.fullname && this.userInfo) {
+      return this.userInfo;
+    }
+    this.applyContext(context);
     await this.writeCache();
-    return info;
+    return context.user_info;
   }
   async getCourses() {
     await this.ensureSession();
@@ -1678,174 +2128,23 @@ var MoodleClient = class {
     return parseFolderHtml(await this.get(FOLDER_VIEW_PATH, { id }), id, this.baseUrl);
   }
   async getForumDiscussion(discussionId) {
-    const cached = this.forumDiscussions.get(discussionId);
-    if (cached) {
-      return cached;
-    }
-    await this.ensureSession();
-    try {
-      const data = await this.call(FUNC_GET_DISCUSSION_POSTS, {
-        discussionid: discussionId,
-        sortby: "created",
-        sortdirection: "ASC",
-        includeinlineattachments: true
-      });
-      const discussion2 = parseForumDiscussion(data, discussionId);
-      if (discussion2.group_id <= 0) {
-        try {
-          const html = await this.get(FORUM_DISCUSS_PATH, { d: discussionId });
-          [discussion2.group_id, discussion2.group_name] = parseForumDiscussionGroupHtml(html);
-        } catch {
-        }
-      }
-      this.forumDiscussions.set(discussionId, discussion2);
-      return discussion2;
-    } catch (error) {
-      if (!(error instanceof MoodleAPIError) || !["servicenotavailable", "accessexception"].includes(error.moodleErrorCode ?? "")) {
-        throw error;
-      }
-    }
-    const discussion = parseForumDiscussionHtml(await this.get(FORUM_DISCUSS_PATH, { d: discussionId }), this.baseUrl, discussionId);
-    this.forumDiscussions.set(discussionId, discussion);
-    return discussion;
+    return this.forum.getForumDiscussion(discussionId);
   }
   async getForumViewCmid(discussionId) {
-    return parseForumViewCmidFromDiscussionHtml(await this.get(FORUM_DISCUSS_PATH, { d: discussionId }));
+    return this.forum.getForumViewCmid(discussionId);
   }
   async resolveCourseIdForUrl(url) {
     return parseCourseIdFromPageHtml(await this.getAbsolute(url));
   }
   async getForumDiscussionRefs(forumCmid) {
-    const cached = this.forumRefs.get(forumCmid);
-    if (cached) {
-      return cached;
-    }
-    const rootHtml = await this.get(FORUM_VIEW_PATH, { id: forumCmid });
-    const groups = parseForumGroupsHtml(rootHtml);
-    const refs = groups.length ? [] : parseForumDiscussionRefsHtml(rootHtml, this.baseUrl);
-    const seen = new Set(refs.map((ref) => ref.id));
-    for (const [groupId, groupName] of groups) {
-      const html = await this.get(FORUM_VIEW_PATH, { id: forumCmid, group: groupId });
-      for (const ref of parseForumDiscussionRefsHtml(html, this.baseUrl)) {
-        if (seen.has(ref.id)) {
-          continue;
-        }
-        ref.group_id = groupId;
-        ref.group_name = groupName;
-        seen.add(ref.id);
-        refs.push(ref);
-      }
-    }
-    this.forumRefs.set(forumCmid, refs);
-    return refs;
-  }
-  async getCourseForums(courseId, courseName = "") {
-    const sections = await this.getCourseContents(courseId);
-    return sections.flatMap(
-      (section) => section.activities.filter((activity) => activity.modname === "forum").map((activity) => ({
-        id: activity.id,
-        name: activity.name,
-        course_id: courseId,
-        course_name: courseName,
-        url: activity.url
-      }))
-    );
+    return this.forum.getForumDiscussionRefs(forumCmid);
   }
   async getForums(courseId) {
-    if (courseId !== void 0) {
-      const courseName = (await this.getCourses()).find((course) => course.id === courseId);
-      return this.getCourseForums(courseId, courseName?.fullname || courseName?.shortname || "");
-    }
-    const refs = [];
-    for (const course of await this.getCourses()) {
-      refs.push(...await this.getCourseForums(course.id, course.fullname || course.shortname));
-    }
-    return refs;
+    return this.forum.getForums(courseId);
   }
   async searchForumContent(options) {
-    const query = options.query.trim();
-    if (!query) {
-      return [];
-    }
-    let forums = await this.getForums(options.courseId);
-    if (options.forumCmid !== void 0) {
-      forums = forums.filter((forum) => forum.id === options.forumCmid);
-      if (!forums.length) {
-        forums = [{ id: options.forumCmid, name: "", course_id: 0, course_name: "", url: `${this.baseUrl}${FORUM_VIEW_PATH}?id=${options.forumCmid}` }];
-      }
-    } else if (options.maxForums !== void 0) {
-      forums = forums.slice(0, options.maxForums);
-    }
-    const hits = [];
-    const seen = /* @__PURE__ */ new Set();
-    for (const forum of forums) {
-      let refs = await this.getForumDiscussionRefs(forum.id);
-      if (options.maxDiscussionsPerForum !== void 0) {
-        refs = refs.slice(0, options.maxDiscussionsPerForum);
-      }
-      for (const ref of refs) {
-        let discussion = null;
-        let latest = 0;
-        let discussionHasUnread = false;
-        if (options.includePostText !== false || options.unreadOnly || options.sortBy === "recent") {
-          discussion = await this.getForumDiscussion(ref.id);
-          latest = Math.max(0, ...discussion.posts.map((post) => post.time_created));
-          discussionHasUnread = discussion.posts.some((post) => post.unread);
-        }
-        if (options.includePostText === false) {
-          const score = matchScore(ref.subject, query);
-          if (score > 0 && (!options.unreadOnly || discussionHasUnread)) {
-            addHit(hits, seen, 400 + score, makeHit(forum, ref, { matched_in: "discussion_subject", snippet: snippetForText(ref.subject, query), unread: discussionHasUnread, time_created: latest }));
-          }
-          continue;
-        }
-        discussion ??= await this.getForumDiscussion(ref.id);
-        let postMatched = false;
-        for (const post of discussion.posts) {
-          const subjectScore = matchScore(post.subject, query);
-          const bodyScore = matchScore(post.message_text, query);
-          if (subjectScore <= 0 && bodyScore <= 0) {
-            continue;
-          }
-          if (options.unreadOnly && !post.unread) {
-            continue;
-          }
-          postMatched = true;
-          const matched_in = subjectScore >= bodyScore ? "post_subject" : "post_body";
-          const matchedText = matched_in === "post_subject" ? post.subject : post.message_text;
-          addHit(
-            hits,
-            seen,
-            300 + Math.max(subjectScore, bodyScore),
-            makeHit(forum, ref, {
-              group_id: discussion.group_id || ref.group_id,
-              group_name: discussion.group_name || ref.group_name,
-              discussion_subject: discussion.subject || ref.subject,
-              post_id: post.id,
-              author_name: post.author.fullname,
-              matched_in,
-              snippet: snippetForText(matchedText, query),
-              unread: post.unread,
-              time_created: post.time_created,
-              url: post.url || ref.url
-            })
-          );
-        }
-        if (!postMatched) {
-          const score = matchScore(ref.subject, query);
-          if (score > 0 && (!options.unreadOnly || discussionHasUnread)) {
-            addHit(hits, seen, 400 + score, makeHit(forum, ref, { matched_in: "discussion_subject", snippet: snippetForText(ref.subject, query), unread: discussionHasUnread, time_created: latest }));
-          }
-        }
-      }
-    }
-    hits.sort((a, b) => {
-      if (options.sortBy === "recent") {
-        return b[1].time_created - a[1].time_created || b[0] - a[0] || compareHit(a[1], b[1]);
-      }
-      return b[0] - a[0] || compareHit(a[1], b[1]);
-    });
-    return hits.slice(0, options.limit ?? 20).map(([, hit]) => hit);
+    const { query, ...searchOptions } = options;
+    return searchForumContent(this.forum, query, { ...searchOptions, baseUrl: this.baseUrl });
   }
   async callBatch(requests) {
     await this.ensureSession();
@@ -2030,85 +2329,11 @@ function authToClientSession(auth) {
     }
   };
 }
-function filterDiscussionToPost(discussion, postId) {
-  if (postId === null) {
-    return discussion;
-  }
-  const posts = discussion.posts.filter((post) => post.id === postId);
-  if (!posts.length) {
-    throw new NotFoundError(`Post ${postId} was not found in discussion ${discussion.id}.`);
-  }
-  return { ...discussion, posts };
-}
 function queryMatches(text, query) {
   const haystack = text.toLowerCase().split(/\s+/).join(" ");
   const needle = query.toLowerCase().split(/\s+/).join(" ");
   return needle ? haystack.includes(needle) || needle.split(" ").every((token) => haystack.includes(token)) : true;
 }
-function matchScore(text, query) {
-  const haystack = text.toLowerCase().split(/\s+/).join(" ");
-  const normalized = query.toLowerCase().split(/\s+/).join(" ");
-  const tokens = normalized.split(/\s+/).filter(Boolean);
-  if (!haystack || !normalized) {
-    return 0;
-  }
-  if (haystack.includes(normalized)) {
-    return 100 + normalized.length;
-  }
-  if (tokens.length && tokens.every((token) => haystack.includes(token))) {
-    return 60 + tokens.length;
-  }
-  return 0;
-}
-function snippetForText(text, query, maxLen = 120) {
-  const cleaned = text.split(/\s+/).join(" ").trim();
-  if (!cleaned || cleaned.length <= maxLen) {
-    return cleaned;
-  }
-  const normalized = query.toLowerCase().split(/\s+/).join(" ");
-  const lower = cleaned.toLowerCase();
-  let start = lower.indexOf(normalized);
-  if (start < 0) {
-    start = normalized.split(/\s+/).map((token) => lower.indexOf(token)).find((index) => index >= 0) ?? -1;
-  }
-  if (start < 0) {
-    return `${cleaned.slice(0, maxLen - 1)}...`;
-  }
-  const left = Math.max(0, start - Math.floor(maxLen / 2));
-  const right = Math.min(cleaned.length, left + maxLen);
-  return `${left > 0 ? "..." : ""}${cleaned.slice(left, right)}${right < cleaned.length ? "..." : ""}`;
-}
-function makeHit(forum, ref, override) {
-  return {
-    course_id: forum.course_id,
-    course_name: forum.course_name,
-    forum_id: forum.id,
-    forum_name: forum.name,
-    group_id: ref.group_id,
-    group_name: ref.group_name,
-    discussion_id: ref.id,
-    discussion_subject: ref.subject,
-    post_id: 0,
-    author_name: "",
-    matched_in: "",
-    snippet: "",
-    unread: false,
-    time_created: 0,
-    url: ref.url,
-    ...override
-  };
-}
-function addHit(hits, seen, score, hit) {
-  const key = `${hit.discussion_id}:${hit.post_id}`;
-  if (seen.has(key)) {
-    return;
-  }
-  seen.add(key);
-  hits.push([score, hit]);
-}
-function compareHit(a, b) {
-  return a.course_name.localeCompare(b.course_name) || a.forum_name.localeCompare(b.forum_name) || a.discussion_id - b.discussion_id || a.post_id - b.post_id;
-}
 function isRecord3(value) {
   return !!value && typeof value === "object" && !Array.isArray(value);
 }
@@ -2456,6 +2681,43 @@ function formatForumCheckResults(forumCmid, rows) {
   }
   return lines.join("\n");
 }
+function formatAuthStatus(status) {
+  return formatKeyValues([
+    ["Site", status.base_url],
+    ["Cached session", status.session_cached ? "yes" : "no"],
+    ["Cache age", status.cache_age_minutes === null ? "" : `${status.cache_age_minutes} min`],
+    ["Session alive", status.session_alive === null ? status.session_cached ? "unknown" : "" : status.session_alive ? "yes" : "no"],
+    ["Server timeout in", formatDuration(status.session_time_remaining_seconds)],
+    ["Keepalive agent", status.keepalive_installed ? `installed (${status.keepalive_plist_path})` : "not installed"]
+  ]);
+}
+function formatKeepaliveResult(result) {
+  switch (result.status) {
+    case "renewed":
+      return `Session renewed${result.time_remaining_seconds ? `; server timeout in ${formatDuration(result.time_remaining_seconds)}` : ""}`;
+    case "reauthenticated":
+      return "Session was expired; re-authenticated from browser/okta cookies";
+    case "expired":
+      return "Session expired and could not be renewed. Log in to Moodle in your browser or run: moodle auth login";
+    case "no_session":
+      return "No cached session to renew. Run any moodle command once, or: moodle auth login";
+    case "unreachable":
+      return "Could not reach the Moodle site; session state unchanged";
+  }
+}
+function formatDuration(seconds) {
+  if (seconds === null) {
+    return "";
+  }
+  if (seconds < 90) {
+    return `${seconds}s`;
+  }
+  const minutes = Math.round(seconds / 60);
+  if (minutes < 90) {
+    return `${minutes} min`;
+  }
+  return `${(minutes / 60).toFixed(1)} h`;
+}
 function preview(value, maxLen = 100) {
   const cleaned = value.split(/\s+/).filter(Boolean).join(" ");
   return cleaned.length <= maxLen ? cleaned : `${cleaned.slice(0, maxLen - 1)}\u2026`;
@@ -2533,12 +2795,24 @@ function isPlainObject(value) {
 
 // src/skills.ts
 import { spawnSync } from "child_process";
-import { readFileSync, writeFileSync } from "fs";
+import { mkdirSync, readFileSync, writeFileSync } from "fs";
 import path from "path";
 var SKILL_NAME = "moodle-cli";
 var SKILL_SOURCE = "https://github.com/bunizao/moodle-cli";
 var SKILLS_SPEC_URL = "https://github.com/vercel-labs/skills";
-var SKILL_DESCRIPTION = "Inspect Moodle data from the terminal with the `moodle` CLI. Use when an agent needs courses, deadlines, grades, alerts, activities, or forum discussions. Prefer JSON output for agent workflows.";
+var SKILL_DESCRIPTION = "Read Moodle data with the `moodle` CLI. Use for authenticated profile, course discovery, deadlines, alerts, sections, activities, grades, assignment or quiz detail, resources, forum search and discussions, supported Moodle URLs, authentication diagnostics, or CLI updates.";
+var SKILL_BUNDLE_TEMPLATES = [
+  ["SKILL.md", "skill.template.md"],
+  ["references/setup-and-auth.md", "skill-references/setup-and-auth.md"],
+  ["references/profile-and-courses.md", "skill-references/profile-and-courses.md"],
+  ["references/deadlines-and-alerts.md", "skill-references/deadlines-and-alerts.md"],
+  ["references/coursework-and-grades.md", "skill-references/coursework-and-grades.md"],
+  ["references/forums.md", "skill-references/forums.md"],
+  ["references/output-and-errors.md", "skill-references/output-and-errors.md"],
+  ["references/maintenance.md", "skill-references/maintenance.md"],
+  ["references/command-reference.md", "skill-references/command-reference.md"],
+  ["agents/openai.yaml", "skill-agents/openai.yaml"]
+];
 function formatSkillSummary() {
   return [
     `Name: ${SKILL_NAME}`,
@@ -2547,7 +2821,7 @@ function formatSkillSummary() {
     `Spec: ${SKILLS_SPEC_URL}`,
     `Install: npx skills add ${SKILL_SOURCE}`,
     "CLI alias: moodle skills add (falls back to npm exec)",
-    "Generate: moodle skills generate"
+    "Generate: moodle skills generate (writes SKILL.md, references/, and agents/)"
   ].join("\n");
 }
 function buildSkillsAddCommand(extraArgs = [], launcher = "npx") {
@@ -2585,15 +2859,15 @@ function extractCommanderCommands(program) {
     flags: row.flags
   }));
 }
-function generateSkillMarkdown(input) {
-  if (isGenerateOptions(input)) {
-    return renderSkillMarkdown(input.commands, input.template);
-  }
-  const template = readSkillTemplate();
-  return renderSkillMarkdown(extractCommanderCommands(input), template);
-}
 function writeGeneratedSkill(program, target = "SKILL.md") {
-  writeFileSync(target, generateSkillMarkdown(program), "utf8");
+  const commands = extractCommanderCommands(program);
+  const targetDir = path.dirname(target);
+  for (const [relativeTarget, relativeTemplate] of SKILL_BUNDLE_TEMPLATES) {
+    const outputPath = relativeTarget === "SKILL.md" ? target : path.join(targetDir, relativeTarget);
+    mkdirSync(path.dirname(outputPath), { recursive: true });
+    const template = readSkillTemplate(relativeTemplate);
+    writeFileSync(outputPath, renderSkillMarkdown(commands, template), "utf8");
+  }
 }
 function renderSkillMarkdown(commands, template) {
   const replacements = {
@@ -2667,6 +2941,8 @@ function renderIntentTable() {
       ["Show grades for a course", "moodle grades COURSE_ID --json"],
       ["Find the best forum match", "moodle forum find QUERY --json"],
       ["Open a forum discussion URL or ID", "moodle forum discussion DISCUSSION_OR_URL --json"],
+      ["Check session freshness or authentication state", "moodle auth status --json"],
+      ["Keep the session alive to avoid repeated logins", "moodle auth keepalive install"],
       ["Check whether the CLI has an update", "moodle update --json"],
       ["Install this agent skill", "moodle skills add"]
     ]
@@ -2751,11 +3027,8 @@ function isCommandAvailable(name, runCommand) {
 function isHiddenCommand(command) {
   return Boolean(command.hidden || command._hidden);
 }
-function isGenerateOptions(value) {
-  return "template" in value && "commands" in value;
-}
-function readSkillTemplate() {
-  return readFileSync(path.join(process.cwd(), "src", "skill.template.md"), "utf8");
+function readSkillTemplate(relativePath = "skill.template.md") {
+  return readFileSync(path.join(process.cwd(), "src", relativePath), "utf8");
 }
 function findLongFlag(flags) {
   return flags.split(/[,\s]+/).find((part) => part.startsWith("--")) ?? "";
@@ -2916,8 +3189,227 @@ function errorMessage(error) {
   return error instanceof Error ? error.message : String(error);
 }
 
+// src/keepalive.ts
+import { spawnSync as spawnSync3 } from "child_process";
+import { realpathSync } from "fs";
+import { mkdir as mkdir3, rm as rm3, stat as stat2, writeFile as writeFile3 } from "fs/promises";
+import { homedir as homedir4 } from "os";
+import { dirname as dirname3, join as join4 } from "path";
+async function touchMoodleSession(baseUrl, cookie, sesskey, fetchImpl = fetch, extend = true) {
+  const methods = extend ? [FUNC_SESSION_TOUCH, FUNC_SESSION_TIME_REMAINING] : [FUNC_SESSION_TIME_REMAINING];
+  const url = `${baseUrl.replace(/\/$/, "")}${AJAX_SERVICE_PATH}?sesskey=${encodeURIComponent(sesskey)}&info=${methods.join(",")}`;
+  let response;
+  try {
+    response = await fetchImpl(url, {
+      method: "POST",
+      headers: {
+        "content-type": "application/json",
+        cookie: `${cookie.name}=${cookie.value}`
+      },
+      body: JSON.stringify(methods.map((methodname, index) => ({ index, methodname, args: {} })))
+    });
+  } catch {
+    return { alive: null, timeRemainingSeconds: null };
+  }
+  if (!response.ok) {
+    return { alive: null, timeRemainingSeconds: null };
+  }
+  let body;
+  try {
+    body = await response.json();
+  } catch {
+    return { alive: false, timeRemainingSeconds: null };
+  }
+  if (!Array.isArray(body) || !body.length) {
+    return { alive: null, timeRemainingSeconds: null };
+  }
+  const first2 = body[0];
+  if (first2?.error) {
+    const exception = first2.exception;
+    const errorcode = typeof exception?.errorcode === "string" ? exception.errorcode : "";
+    if (errorcode === "servicerequireslogin" || errorcode === "sitepolicynotagreed") {
+      return { alive: false, timeRemainingSeconds: null };
+    }
+    return { alive: null, timeRemainingSeconds: null };
+  }
+  const last = body[body.length - 1];
+  const data = last?.data;
+  const timeRemaining = typeof data?.timeremaining === "number" ? data.timeremaining : null;
+  return { alive: true, timeRemainingSeconds: timeRemaining };
+}
+async function keepAliveOnce(baseUrl, options = {}) {
+  const session = await readCachedSession(baseUrl, {
+    homeDir: options.homeDir,
+    ttlMs: Number.MAX_SAFE_INTEGER,
+    now: options.now
+  });
+  if (!session) {
+    return { status: "no_session", time_remaining_seconds: null };
+  }
+  const touch = await touchMoodleSession(
+    baseUrl,
+    { name: session.cookieName, value: session.cookieValue },
+    session.sesskey,
+    options.fetchImpl ?? fetch
+  );
+  if (touch.alive === true) {
+    await writeCachedSession({ ...session, savedAt: (options.now ?? Date.now)() }, { homeDir: options.homeDir });
+    return { status: "renewed", time_remaining_seconds: touch.timeRemainingSeconds };
+  }
+  if (touch.alive === null) {
+    return { status: "unreachable", time_remaining_seconds: null };
+  }
+  if (options.renewOnExpiry === false) {
+    return { status: "expired", time_remaining_seconds: null };
+  }
+  const authenticate = options.authenticate ?? ((url) => getAuthenticatedSession(url, {
+    homeDir: options.homeDir,
+    fetch: options.fetchImpl,
+    noCache: true,
+    now: options.now,
+    // Background runs must never block on an interactive Okta login.
+    nonInteractive: true
+  }));
+  try {
+    await authenticate(baseUrl);
+    return { status: "reauthenticated", time_remaining_seconds: null };
+  } catch {
+    return { status: "expired", time_remaining_seconds: null };
+  }
+}
+async function getAuthStatus(baseUrl, options = {}) {
+  const now = options.now ?? Date.now;
+  const keepalive = await keepaliveStatus(options.homeDir);
+  const session = await readCachedSession(baseUrl, {
+    homeDir: options.homeDir,
+    ttlMs: Number.MAX_SAFE_INTEGER,
+    now: options.now
+  });
+  if (!session) {
+    return {
+      base_url: baseUrl,
+      session_cached: false,
+      cache_age_minutes: null,
+      session_alive: null,
+      session_time_remaining_seconds: null,
+      keepalive_installed: keepalive.installed,
+      keepalive_plist_path: keepalive.plist_path
+    };
+  }
+  const touch = await touchMoodleSession(
+    baseUrl,
+    { name: session.cookieName, value: session.cookieValue },
+    session.sesskey,
+    options.fetchImpl ?? fetch,
+    false
+  );
+  return {
+    base_url: baseUrl,
+    session_cached: true,
+    cache_age_minutes: Math.max(0, Math.round((now() - session.savedAt) / 6e4)),
+    session_alive: touch.alive,
+    session_time_remaining_seconds: touch.timeRemainingSeconds,
+    keepalive_installed: keepalive.installed,
+    keepalive_plist_path: keepalive.plist_path
+  };
+}
+function keepalivePlistPath(homeDir = homedir4()) {
+  return join4(homeDir, "Library/LaunchAgents", `${KEEPALIVE_LAUNCH_AGENT_LABEL}.plist`);
+}
+function keepaliveLogPath(homeDir = homedir4()) {
+  return join4(homeDir, CACHE_DIR_NAME, KEEPALIVE_LOG_FILENAME);
+}
+function keepaliveProgramArguments(execPath = process.execPath, argv1 = process.argv[1] ?? "") {
+  const resolvedArgv1 = argv1 ? safeRealpath(argv1) : "";
+  const tail = ["auth", "keepalive", "--json"];
+  if (!resolvedArgv1 || resolvedArgv1 === safeRealpath(execPath)) {
+    return [execPath, ...tail];
+  }
+  return [execPath, resolvedArgv1, ...tail];
+}
+function buildKeepalivePlist(programArguments, intervalMinutes, logPath) {
+  const args = programArguments.map((arg) => `    <string>${escapeXml(arg)}</string>`).join("\n");
+  return [
+    '<?xml version="1.0" encoding="UTF-8"?>',
+    '<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">',
+    '<plist version="1.0">',
+    "<dict>",
+    "  <key>Label</key>",
+    `  <string>${KEEPALIVE_LAUNCH_AGENT_LABEL}</string>`,
+    "  <key>ProgramArguments</key>",
+    "  <array>",
+    args,
+    "  </array>",
+    "  <key>StartInterval</key>",
+    `  <integer>${Math.round(intervalMinutes * 60)}</integer>`,
+    "  <key>RunAtLoad</key>",
+    "  <true/>",
+    "  <key>StandardOutPath</key>",
+    `  <string>${escapeXml(logPath)}</string>`,
+    "  <key>StandardErrPath</key>",
+    `  <string>${escapeXml(logPath)}</string>`,
+    "</dict>",
+    "</plist>",
+    ""
+  ].join("\n");
+}
+async function installKeepalive(options = {}) {
+  const platform = options.platform ?? process.platform;
+  if (platform !== "darwin") {
+    throw new Error(
+      "Automatic keepalive install requires macOS launchd. Add a cron entry instead: */30 * * * * moodle auth keepalive --json"
+    );
+  }
+  const homeDir = options.homeDir ?? homedir4();
+  const intervalMinutes = options.intervalMinutes ?? KEEPALIVE_DEFAULT_INTERVAL_MINUTES;
+  const plistPath = keepalivePlistPath(homeDir);
+  const logPath = keepaliveLogPath(homeDir);
+  const command = keepaliveProgramArguments(options.execPath, options.argv1);
+  await mkdir3(dirname3(plistPath), { recursive: true });
+  await mkdir3(dirname3(logPath), { recursive: true, mode: 448 });
+  await writeFile3(plistPath, buildKeepalivePlist(command, intervalMinutes, logPath), "utf8");
+  const runCommand = options.runCommand ?? spawnSync3;
+  const uid = options.uid ?? (typeof process.getuid === "function" ? process.getuid() : 0);
+  runCommand("launchctl", ["bootout", `gui/${uid}/${KEEPALIVE_LAUNCH_AGENT_LABEL}`], { stdio: "ignore" });
+  const bootstrap = runCommand("launchctl", ["bootstrap", `gui/${uid}`, plistPath], { stdio: "ignore" });
+  if (bootstrap.error || bootstrap.status !== 0) {
+    const legacy = runCommand("launchctl", ["load", "-w", plistPath], { stdio: "ignore" });
+    if (legacy.error || legacy.status !== 0) {
+      throw new Error(`Failed to register the launch agent. Try manually: launchctl bootstrap gui/${uid} ${plistPath}`);
+    }
+  }
+  return { plist_path: plistPath, interval_minutes: intervalMinutes, log_path: logPath, command };
+}
+async function uninstallKeepalive(options = {}) {
+  const homeDir = options.homeDir ?? homedir4();
+  const plistPath = keepalivePlistPath(homeDir);
+  const runCommand = options.runCommand ?? spawnSync3;
+  const uid = options.uid ?? (typeof process.getuid === "function" ? process.getuid() : 0);
+  runCommand("launchctl", ["bootout", `gui/${uid}/${KEEPALIVE_LAUNCH_AGENT_LABEL}`], { stdio: "ignore" });
+  await rm3(plistPath, { force: true });
+  return { installed: false, plist_path: plistPath };
+}
+async function keepaliveStatus(homeDir = homedir4()) {
+  const plistPath = keepalivePlistPath(homeDir);
+  try {
+    return { installed: (await stat2(plistPath)).isFile(), plist_path: plistPath };
+  } catch {
+    return { installed: false, plist_path: plistPath };
+  }
+}
+function safeRealpath(path3) {
+  try {
+    return realpathSync(path3);
+  } catch {
+    return path3;
+  }
+}
+function escapeXml(value) {
+  return value.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;").replace(/'/g, "&apos;");
+}
+
 // src/version.ts
-var VERSION = "0.5.5";
+var VERSION = "0.6.0";
 
 // src/url-resolver.ts
 function looksLikeUrl(value) {
@@ -3026,24 +3518,6 @@ function parseActivityReference(value, labelOrOptions, expectedPathValue) {
   }
   return Number(id);
 }
-function parseDiscussionReference(value) {
-  const raw = value.trim();
-  if (/^\d+$/.test(raw)) {
-    return { discussionId: Number(raw), postId: null };
-  }
-  let parsed;
-  try {
-    parsed = new URL(raw);
-  } catch {
-    throw new UsageError("DISCUSSION must be a numeric ID or a full discuss.php URL.");
-  }
-  const discussion = parsed.searchParams.get("d");
-  if (!discussion || !/^\d+$/.test(discussion)) {
-    throw new UsageError("Could not find discussion ID in URL query (expected ?d=...).");
-  }
-  const postId = parsed.hash.startsWith("#p") && /^\d+$/.test(parsed.hash.slice(2)) ? Number(parsed.hash.slice(2)) : null;
-  return { discussionId: Number(discussion), postId };
-}
 
 // src/cli.ts
 function buildProgram(io = {}) {
@@ -3147,7 +3621,7 @@ ${overview.alerts ? formatAlerts(overview.alerts) : ""}`, options);
   });
   addOutputOptions(forum.command("discussions").description("List discussions from a forum.").argument("<forum>", "Forum ID or URL")).option("--limit <number>", "Maximum number of discussions.", parsePositiveInt, 50).option("--query <query>", "Filter discussion titles by query.").action(async (forumRef, options) => {
     const client = await runtime.getClient();
-    const forumId = await parseForumReference(client, forumRef);
+    const forumId = await parseForumReference(forumRef, (discussionId) => client.getForumViewCmid(discussionId));
     let refs = await client.getForumDiscussionRefs(forumId);
     if (options.query) {
       refs = refs.filter((ref) => queryMatches2(ref.subject, options.query));
@@ -3169,25 +3643,55 @@ ${overview.alerts ? formatAlerts(overview.alerts) : ""}`, options);
   addForumSearchCommand(forum.command("find").description("Find the best forum match.").option("--list", "Return a shortlist.").option("--body", "Resolve the target body."), runtime, 5, true);
   addOutputOptions(forum.command("check").description("Validate discussion rendering.").argument("<forum>", "Forum ID or URL")).option("--limit <number>", "Maximum number of discussions.", parsePositiveInt, 20).action(async (forumRef, options) => {
     const client = await runtime.getClient();
-    const forumId = await parseForumReference(client, forumRef);
-    const refs = (await client.getForumDiscussionRefs(forumId)).slice(0, options.limit);
-    const results = [];
-    for (const ref of refs) {
-      try {
-        const discussion = await client.getForumDiscussion(ref.id);
-        results.push({
-          discussion_id: ref.id,
-          subject: ref.subject,
-          ok: true,
-          posts: discussion.posts.length,
-          images: discussion.posts.reduce((total, post) => total + post.image_urls.length, 0)
-        });
-      } catch (error) {
-        results.push({ discussion_id: ref.id, subject: ref.subject, ok: false, error: error instanceof Error ? error.message : String(error) });
-      }
-    }
+    const forumId = await parseForumReference(forumRef, (discussionId) => client.getForumViewCmid(discussionId));
+    const results = await checkForumDiscussions(client, forumId, options.limit);
     runtime.output(results, () => formatForumCheckResults(forumId, results), options);
   });
+  const auth = program.command("auth").description("Session and keepalive utilities.");
+  addOutputOptions(auth.command("status").description("Show cached session freshness and keepalive state.")).action(
+    async (options) => {
+      const baseUrl = await runtime.baseUrl();
+      const status = await getAuthStatus(baseUrl, { homeDir: io.homeDir, fetchImpl: io.fetchImpl });
+      runtime.output(status, () => formatAuthStatus(status), options);
+    }
+  );
+  addOutputOptions(auth.command("login").description("Force a fresh login and refresh the session cache.")).action(
+    async (options) => {
+      const baseUrl = await runtime.baseUrl();
+      await invalidateCachedSession(baseUrl, { homeDir: io.homeDir });
+      const session = await getAuthenticatedSession(baseUrl, { env: io.env, fetch: io.fetchImpl, homeDir: io.homeDir, noCache: true });
+      const result = { base_url: baseUrl, userid: session.userid, cookie_source: session.cookie.source ?? "unknown" };
+      runtime.output(result, () => `Authenticated as userid ${result.userid} via ${result.cookie_source}`, options);
+    }
+  );
+  const keepalive = addOutputOptions(
+    auth.command("keepalive").description("Renew the Moodle session once; used by the background keepalive agent.").option("--no-renew", "Only touch the session; skip re-login when it is expired.")
+  ).action(async (options) => {
+    const baseUrl = await runtime.baseUrl();
+    const result = await keepAliveOnce(baseUrl, { homeDir: io.homeDir, fetchImpl: io.fetchImpl, renewOnExpiry: options.renew });
+    runtime.output(result, () => formatKeepaliveResult(result), options);
+  });
+  addOutputOptions(
+    keepalive.command("install").description("Install a macOS launch agent that renews the session periodically.").option("--interval <minutes>", "Renewal interval in minutes.", parsePositiveInt)
+  ).action(async (options) => {
+    await runtime.baseUrl();
+    const result = await installKeepalive({ homeDir: io.homeDir, intervalMinutes: options.interval });
+    runtime.output(result, () => `Keepalive installed: renews every ${result.interval_minutes} min
+Agent: ${result.plist_path}
+Log: ${result.log_path}`, options);
+  });
+  addOutputOptions(keepalive.command("uninstall").description("Remove the keepalive launch agent.")).action(
+    async (options) => {
+      const result = await uninstallKeepalive({ homeDir: io.homeDir });
+      runtime.output(result, () => `Keepalive removed (${result.plist_path})`, options);
+    }
+  );
+  addOutputOptions(keepalive.command("status").description("Show whether the keepalive launch agent is installed.")).action(
+    async (options) => {
+      const result = await keepaliveStatus(io.homeDir);
+      runtime.output(result, () => result.installed ? `Keepalive installed (${result.plist_path})` : "Keepalive not installed", options);
+    }
+  );
   addOutputOptions(program.command("update").description("Check for updates and upgrade the installed CLI.")).option("--check-only", "Only check for updates; do not install.").action(async (options) => {
     try {
       const info = await checkForUpdates(VERSION, io.fetchImpl);
@@ -3219,9 +3723,9 @@ ${overview.alerts ? formatAlerts(overview.alerts) : ""}`, options);
     stdout.write(`${formatSkillSummary()}
 `);
   });
-  skills.command("generate").description("Regenerate SKILL.md from the CLI command tree.").action(() => {
+  skills.command("generate").description("Regenerate the agent skill bundle from the CLI command tree.").action(() => {
     writeGeneratedSkill(program);
-    stdout.write("Generated SKILL.md\n");
+    stdout.write("Generated Moodle skill bundle\n");
   });
   skills.command("add").description("Install the published skill through npx skills add.").allowUnknownOption(true).action((_options, command) => installSkill(command.args));
   hideCommand(skills.command("install").allowUnknownOption(true)).action((_options, command) => installSkill(command.args));
@@ -3334,7 +3838,7 @@ function addForumSearchCommand(command, runtime, defaultLimit, findMode) {
   addOutputOptions(command.argument("<query>", "Search query")).option("--course <course>", "Restrict to a course ID or unique course name match.").option("--forum <forum>", "Restrict to a forum ID or forum URL.").option("--titles-only", "Only search discussion titles.").option("--unread-only", "Only include unread matches.").option("--recent", "Sort matches by newest activity.").option("--limit-forums <number>", "Maximum number of forums to scan.", parsePositiveInt).option("--limit-discussions <number>", "Maximum number of discussions per forum.", parsePositiveInt).option("--limit <number>", "Maximum number of matches.", parsePositiveInt, defaultLimit).action(async (query, options) => {
     const client = await runtime.getClient();
     const courseId = options.course ? await client.resolveCourseReference(options.course) : void 0;
-    const forumCmid = options.forum ? await parseForumReference(client, options.forum) : void 0;
+    const forumCmid = options.forum ? await parseForumReference(options.forum, (discussionId) => client.getForumViewCmid(discussionId)) : void 0;
     const limit = findMode && !options.list ? 1 : options.limit;
     const hits = await client.searchForumContent({
       query,
@@ -3356,29 +3860,6 @@ function addForumSearchCommand(command, runtime, defaultLimit, findMode) {
     runtime.output(output, () => formatForumSearchHits(Array.isArray(output) ? output : output ? [output] : []), options);
   });
 }
-async function parseForumReference(client, value) {
-  const raw = value.trim();
-  if (/^\d+$/.test(raw)) {
-    return Number(raw);
-  }
-  const parsed = new URL(raw);
-  if (parsed.pathname.endsWith("/mod/forum/view.php")) {
-    const id = parsed.searchParams.get("id");
-    if (id && /^\d+$/.test(id)) {
-      return Number(id);
-    }
-  }
-  if (parsed.pathname.endsWith("/mod/forum/discuss.php")) {
-    const id = parsed.searchParams.get("d");
-    if (id && /^\d+$/.test(id)) {
-      const forumId = await client.getForumViewCmid(Number(id));
-      if (forumId) {
-        return forumId;
-      }
-    }
-  }
-  throw new UsageError("Unsupported forum URL. Use a view.php?id=... or discuss.php?d=... URL.");
-}
 function addOutputOptions(command) {
   return command.option("--json", "Output as JSON.").option("--yaml", "Output as YAML.").option("--table", "Force human output.").option("--fields <fields>", "Keep only listed top-level fields in structured output.");
 }
@@ -3462,7 +3943,7 @@ function queryMatches2(text, query) {
   const needle = query.toLowerCase().split(/\s+/).join(" ");
   return needle ? haystack.includes(needle) || needle.split(" ").every((token) => haystack.includes(token)) : true;
 }
-var isMain = process.argv[1] ? realpathSync(fileURLToPath(import.meta.url)) === realpathSync(process.argv[1]) : false;
+var isMain = process.argv[1] ? realpathSync2(fileURLToPath(import.meta.url)) === realpathSync2(process.argv[1]) : false;
 if (isMain) {
   runCli().then((code) => {
     process.exitCode = code;