moodle-cli 0.5.5 → 0.6.0

package/README.md

@@ -57,6 +57,19 @@ base_url: https://school.example.edu
 
 Use a root URL only, not `/login/index.php` or `/my/`.
 
+### Session Keepalive
+
+Moodle expires idle sessions server-side, which normally forces a fresh SSO login. The CLI can renew the session in the background instead:
+
+```bash
+moodle auth status               # cache freshness + server session state
+moodle auth keepalive            # renew once; re-login from browser/okta cookies if expired
+moodle auth keepalive install    # macOS launch agent, renews every 30 min
+moodle auth login                # force a fresh login
+```
+
+On Linux, add a cron entry: `*/30 * * * * moodle auth keepalive --json`.
+
 ## Usage
 
 ```bash
@@ -137,16 +150,20 @@ The CLI alias delegates to the same command:
 moodle skills add
 ```
 
-Regenerate `SKILL.md` from the command tree:
+Regenerate the skill bundle from the command tree and source templates:
 
 ```bash
 npm run build
 npm run skill:generate
-git diff --exit-code SKILL.md
+git diff --exit-code -- SKILL.md references agents/openai.yaml
 ```
 
+`SKILL.md` routes agents to focused guidance under `references/`; the exact command and output references remain generated from the CLI.
+
 ## Development
 
+The project typechecks with TypeScript 7 and bundles the Node.js CLI with tsup/esbuild.
+
 ```bash
 npm install
 npm run check

package/SKILL.md

@@ -1,167 +1,36 @@
 ---
 name: moodle-cli
-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.
+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.
 ---
 
-# moodle-cli
+# Moodle CLI
 
-<!-- Generated by `moodle skills generate`. Edit `src/skill.template.md` for prose changes. -->
+<!-- Generated by `moodle skills generate`. Edit `src/skill.template.md` and `src/skill-references/`. -->
 
-Use `moodle` for read-only Moodle access.
+Use `moodle` for read-only Moodle inspection.
 
-## Defaults
+## Core Steps
 
-Use the narrowest command that answers the request.
+1. Classify the request with the branch map below and read that reference file before running a command.
+2. Run the narrowest command that answers the request. Prefer `--json`; add `--fields` when only a few top-level fields matter.
+3. Parse the result locally and answer with the requested facts, exact dates, and relevant Moodle links. The task is complete when the answer is supported by command output rather than inference.
 
-Prefer JSON for agent work. `--json` is explicit, and piped stdout defaults to JSON automatically. Use `--fields` to keep only the top-level fields you need.
+Resolve an unfamiliar course name with `moodle courses --json` before using a course-specific command. Use `moodle overview --json` only for an explicitly combined snapshot.
 
-Omit `--json` only when a human explicitly wants the formatted terminal view. Use `--table` to force human output in a pipe.
+## Branch Map
 
-Resolve course IDs with `moodle courses --json` before running course-specific commands when the user gives only a course name.
+- **Installation, configuration, authentication failure, or session keepalive**: read [references/setup-and-auth.md](references/setup-and-auth.md).
+- **Profile, course discovery, sections, or activity lists**: read [references/profile-and-courses.md](references/profile-and-courses.md).
+- **Deadlines, todo items, alerts, or a combined snapshot**: read [references/deadlines-and-alerts.md](references/deadlines-and-alerts.md).
+- **Grades or assignment, quiz, resource, link, page, and folder detail**: read [references/coursework-and-grades.md](references/coursework-and-grades.md).
+- **Forum discovery, search, discussions, posts, groups, or rendering checks**: read [references/forums.md](references/forums.md).
+- **Output selection, field filtering, error handling, or exit codes**: read [references/output-and-errors.md](references/output-and-errors.md).
+- **Updates, skill installation, or skill regeneration**: read [references/maintenance.md](references/maintenance.md).
+- **Exact syntax or all flags**: read [references/command-reference.md](references/command-reference.md).
 
-Avoid `moodle overview --json` unless the user explicitly asks for a combined snapshot across courses, deadlines, and alerts.
+## Shared Rules
 
-## Setup
-
-```bash
-npm i -g moodle-cli
-# or run without installing
-npx moodle-cli --help
-```
-
-Standalone binaries are published on GitHub Releases.
-
-Existing PyPI users should migrate:
-
-```bash
-uv tool uninstall moodle-cli
-npm i -g moodle-cli
-```
-
-Authenticate with an active Moodle browser session, `MOODLE_SESSION`, or `okta-auth-cli`.
-
-Set `MOODLE_BASE_URL` or let the first run prompt for the Moodle root URL and save it to config.
-
-## Forum Routing
-
-For forum requests, prefer `moodle forum find` over manually chaining `forum forums`, `forum discussions`, and `forum discussion`.
-
-If the user already gives a forum discussion URL, skip search and open it directly with `moodle forum discussion DISCUSSION_OR_URL --json`.
-
-If the user gives a forum view URL or discussion URL and wants to browse nearby discussions, use `moodle forum discussions FORUM_OR_URL --json`.
-
-Use scan budgets first when the site may be large:
-
-- `--course` to narrow to one course
-- `--limit-forums` to cap how many forums to scan
-- `--limit-discussions` to cap how many discussions to scan per forum
-
-Grouped forums are handled automatically. Do not assume an empty default forum page means the forum has no discussions.
-
-Default forum agent flow:
-
-1. Start with `moodle forum find QUERY --json`
-2. Add `--unread-only` when the user wants new or unseen content
-3. Add `--list --limit N` when one result is not enough and you need a shortlist
-4. Add `--body` only when the snippet is insufficient and you need the full target post/discussion
-
-Avoid `moodle forum search` unless you explicitly need a larger result set than `forum find --list`.
-
-## Intent To Command
-
-| User intent | Command |
-| --- | --- |
-| Show my profile or account info | moodle user --json |
-| List my courses | moodle courses --json |
-| Find nearest deadlines or upcoming actions | moodle todo --limit 5 --days 14 --json |
-| List alerts or unread notifications | moodle alerts --limit 10 --json |
-| Show a compact dashboard | moodle overview --todo-limit 5 --alerts-limit 5 --json |
-| Show activities in a course | moodle activities COURSE_ID --json |
-| Show course sections | moodle course COURSE_ID --json |
-| 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 whether the CLI has an update | moodle update --json |
-| Install this agent skill | moodle skills add |
-
-## Command Reference
-
-| Command | Description | Arguments | Flags |
-| --- | --- | --- | --- |
-| moodle activities | List activities in a course. | <course> | --json<br>--yaml<br>--table<br>--fields (value required) |
-| moodle alerts | List notifications and message counts. |  | --json<br>--yaml<br>--table<br>--fields (value required)<br>--limit (default: 20; value required) |
-| moodle assign | Show assignment details. | <assign> | --json<br>--yaml<br>--table<br>--fields (value required) |
-| moodle course | Show course detail with sections. | <course> | --json<br>--yaml<br>--table<br>--fields (value required) |
-| moodle courses | List enrolled courses. |  | --json<br>--yaml<br>--table<br>--fields (value required) |
-| moodle folder | Show folder details. | <folder> | --json<br>--yaml<br>--table<br>--fields (value required) |
-| moodle forum | Forum utilities. |  |  |
-| moodle forum check | Validate discussion rendering. | <forum> | --json<br>--yaml<br>--table<br>--fields (value required)<br>--limit (default: 20; value required) |
-| moodle forum discussion | Show posts in a forum discussion. | <discussion> | --json<br>--yaml<br>--table<br>--fields (value required)<br>--post (value required)<br>--body |
-| moodle forum discussions | List discussions from a forum. | <forum> | --json<br>--yaml<br>--table<br>--fields (value required)<br>--limit (default: 50; value required)<br>--query (value required) |
-| moodle forum find | Find the best forum match. | <query> | --list<br>--body<br>--json<br>--yaml<br>--table<br>--fields (value required)<br>--course (value required)<br>--forum (value required)<br>--titles-only<br>--unread-only<br>--recent<br>--limit-forums (value required)<br>--limit-discussions (value required)<br>--limit (default: 5; value required) |
-| moodle forum forums | List forum activities. | [query] | --json<br>--yaml<br>--table<br>--fields (value required)<br>--course (value required)<br>--limit (default: 50; value required) |
-| moodle forum search | Search forum discussion titles and post text. | <query> | --json<br>--yaml<br>--table<br>--fields (value required)<br>--course (value required)<br>--forum (value required)<br>--titles-only<br>--unread-only<br>--recent<br>--limit-forums (value required)<br>--limit-discussions (value required)<br>--limit (default: 20; value required) |
-| moodle grades | Show grade details for a course. | <course> | --json<br>--yaml<br>--table<br>--fields (value required) |
-| moodle link | Show link details. | <link> | --json<br>--yaml<br>--table<br>--fields (value required) |
-| moodle overview | Show a compact multi-source overview. |  | --json<br>--yaml<br>--table<br>--fields (value required)<br>--todo-limit (default: 5; value required)<br>--todo-days (value required)<br>--alerts-limit (default: 5; value required) |
-| moodle page | Show page details. | <page> | --json<br>--yaml<br>--table<br>--fields (value required) |
-| moodle quiz | Show quiz details. | <quiz> | --json<br>--yaml<br>--table<br>--fields (value required) |
-| moodle resource | Show resource details. | <resource> | --json<br>--yaml<br>--table<br>--fields (value required) |
-| moodle skills | Show skill metadata or delegate to the shared skills CLI. |  |  |
-| moodle skills add | Install the published skill through npx skills add. |  |  |
-| moodle skills generate | Regenerate SKILL.md from the CLI command tree. |  |  |
-| moodle todo | List upcoming actionable timeline items. |  | --json<br>--yaml<br>--table<br>--fields (value required)<br>--limit (default: 20; value required)<br>--days (value required) |
-| moodle update | Check for updates and upgrade the installed CLI. |  | --json<br>--yaml<br>--table<br>--fields (value required)<br>--check-only |
-| moodle user | Show authenticated user info. |  | --json<br>--yaml<br>--table<br>--fields (value required) |
-
-## Agent Output
-
-### Output Contract
-
-- `--json` writes JSON to stdout.
-- `--yaml` writes YAML to stdout when supported.
-- `--table` forces human-readable table/tree output.
-- When stdout is not a TTY, commands default to JSON unless `--table` is set.
-- `--fields a,b,c` keeps only listed top-level fields. Arrays apply the field filter to each item.
-- Invalid `--fields` values are usage errors and list valid fields.
-- With JSON output enabled, errors are one JSON line on stderr: `{"error":true,"code":"auth_failed","message":"...","hint":"..."}`.
-
-Exit codes:
-
-| Code | Meaning |
-| --- | --- |
-| 0 | Success |
-| 1 | Unexpected error |
-| 2 | Authentication or configuration error |
-| 3 | Usage error |
-| 4 | Requested course, activity, forum, or discussion was not found |
-
-## Operating Rules
-
-Parse JSON locally and return a concise answer.
-
-Do not paste full command output unless the user explicitly asks for raw JSON.
-
-If the user asks for "recent", "next", or "nearest", sort by relevance and mention exact timestamps from `due_at` or `created_at`.
-
-If a request is ambiguous between activities, courses, and grades, inspect courses first and then run the smallest follow-up command.
-
-For forum work, do not enumerate forums or discussions first unless the user explicitly asks to browse. Search first, then expand only if needed.
-
-For forum discussion output, prefer structured fields over heuristic text parsing when available:
-
-- `image_urls` for original image links
-- `links` for extracted hyperlinks
-- `tables` for structured table content
-- `group_id` and `group_name` for grouped forum context
-
-## Failure Modes
-
-- Authentication failed: sign in to Moodle in the browser, export `MOODLE_SESSION`, or configure `okta-auth-cli`.
-- Invalid base URL: use the Moodle site root such as `https://school.example.edu`, not `/login/index.php` or `/my/`.
-- Could not check for updates: retry with network access to the npm registry, then run `npm install -g moodle-cli@latest` or download the latest GitHub Release binary.
-
-## Safety
-
-- Treat `MOODLE_SESSION` as a secret and never paste it into chat or logs.
-- The CLI is read-only and does not create or modify Moodle content.
+- Use `--table` only when the user asks for the terminal presentation.
+- Return a concise answer instead of pasting raw output unless raw JSON is requested.
+- Treat `MOODLE_SESSION` as a secret and keep it out of chat, commands shown to the user, and logs.
+- Keep the operation read-only. This CLI inspects Moodle; it does not create or modify Moodle content.

package/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Moodle CLI"
+  short_description: "Inspect courses, grades, deadlines, and forums"
+  default_prompt: "Use $moodle-cli to inspect my Moodle data and answer with the narrowest relevant command."