moodle-cli 0.5.5 → 0.6.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "moodle-cli",
-  "version": "0.5.5",
+  "version": "0.6.0",
   "description": "Terminal-first CLI for Moodle LMS",
   "license": "MIT",
   "type": "module",
@@ -11,17 +11,19 @@
     "dist",
     "README.md",
     "SKILL.md",
+    "references",
+    "agents",
     "LICENSE"
   ],
   "scripts": {
-    "build": "tsup && rm -f dist/.gitignore",
+    "build": "tsc --noEmit && tsup && rm -f dist/.gitignore",
     "check": "tsc --noEmit",
-    "pack:check": "npm pack --dry-run --json | node -e \"let data = ''; process.stdin.on('data', chunk => data += chunk); process.stdin.on('end', () => { const files = JSON.parse(data)[0]?.files?.map(file => file.path) ?? []; if (!files.includes('dist/moodle.js')) throw new Error('npm package is missing dist/moodle.js'); });\"",
+    "pack:check": "npm pack --dry-run --json | node -e \"let data = ''; process.stdin.on('data', chunk => data += chunk); process.stdin.on('end', () => { const files = JSON.parse(data)[0]?.files?.map(file => file.path) ?? []; for (const required of ['dist/moodle.js', 'SKILL.md', 'references/command-reference.md', 'agents/openai.yaml']) if (!files.includes(required)) throw new Error('npm package is missing ' + required); });\"",
     "pack:smoke": "tmp=\"$(mktemp -d)\" && npm pack --pack-destination \"$tmp\" >/dev/null && npm install --prefix \"$tmp/install\" \"$tmp\"/moodle-cli-*.tgz >/dev/null && test \"$(\"$tmp/install/node_modules/.bin/moodle\" --version)\" = \"$(node -p \"JSON.parse(require('node:fs').readFileSync('package.json', 'utf8')).version\")\"",
     "test": "vitest run",
     "test:watch": "vitest",
     "skill:generate": "node dist/moodle.js skills generate",
-    "prepublishOnly": "npm run check && npm run test && npm run build"
+    "prepublishOnly": "npm run test && npm run build"
   },
   "dependencies": {
     "commander": "^14.0.0",
@@ -35,7 +37,7 @@
   "devDependencies": {
     "@types/node": "^24.0.10",
     "tsup": "^8.5.0",
-    "typescript": "^5.8.3",
+    "typescript": "^7.0.2",
     "vitest": "^3.2.4"
   },
   "engines": {

package/references/command-reference.md

@@ -0,0 +1,38 @@
+# Command Reference
+
+Read this file for exact arguments, flags, and defaults after selecting a branch from `SKILL.md`.
+
+| 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 auth | Session and keepalive utilities. |  |  |
+| moodle auth keepalive | Renew the Moodle session once; used by the background keepalive agent. |  | --no-renew<br>--json<br>--yaml<br>--table<br>--fields (value required) |
+| moodle auth keepalive install | Install a macOS launch agent that renews the session periodically. |  | --interval (value required)<br>--json<br>--yaml<br>--table<br>--fields (value required) |
+| moodle auth keepalive status | Show whether the keepalive launch agent is installed. |  | --json<br>--yaml<br>--table<br>--fields (value required) |
+| moodle auth keepalive uninstall | Remove the keepalive launch agent. |  | --json<br>--yaml<br>--table<br>--fields (value required) |
+| moodle auth login | Force a fresh login and refresh the session cache. |  | --json<br>--yaml<br>--table<br>--fields (value required) |
+| moodle auth status | Show cached session freshness and keepalive state. |  | --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 the agent skill bundle 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) |

package/references/coursework-and-grades.md

@@ -0,0 +1,42 @@
+# Coursework and Grades
+
+Read this file for grades or detail about assignments, quizzes, resources, links, pages, and folders.
+
+## Grades
+
+Use a course ID or unique course name:
+
+```bash
+moodle grades COURSE --json
+```
+
+Report the course total and requested grade items. Preserve displayed values and percentages; Moodle gradebooks may expose text such as ranges, letters, or incomplete totals.
+
+## Activity Detail
+
+Each command accepts a numeric module ID or its full Moodle URL:
+
+| Activity | Command |
+| --- | --- |
+| Assignment | `moodle assign ASSIGNMENT --json` |
+| Quiz | `moodle quiz QUIZ --json` |
+| File/resource | `moodle resource RESOURCE --json` |
+| External link | `moodle link LINK --json` |
+| Moodle page | `moodle page PAGE --json` |
+| Folder | `moodle folder FOLDER --json` |
+
+When the user supplies a supported Moodle URL without naming a command, route it directly:
+
+```bash
+moodle 'MOODLE_URL' --json
+```
+
+The CLI recognizes course, grade report, forum, assignment, quiz, resource, link, page, and folder URLs. For another activity URL, it may fall back to the containing course.
+
+## Agent Steps
+
+1. Use the activity-specific command when the activity type is known.
+2. Use direct URL routing when the user already supplied a URL and only wants its content.
+3. Return structured links and files from the result instead of scraping prose from the formatted table.
+
+The branch is complete when the answer identifies the course or module and quotes the grade or activity state returned by Moodle.

package/references/deadlines-and-alerts.md

@@ -0,0 +1,25 @@
+# Deadlines and Alerts
+
+Read this file for upcoming work, due dates, notifications, unread counts, or a combined snapshot.
+
+## Choose the Command
+
+| Need | Command |
+| --- | --- |
+| Nearest actionable items | `moodle todo --limit 5 --days 14 --json` |
+| Notifications and message counts | `moodle alerts --limit 10 --json` |
+| User, courses, todo, and alerts together | `moodle overview --todo-limit 5 --alerts-limit 5 --json` |
+
+Use `todo` for “next,” “due,” “deadline,” and “upcoming.” Add `--days N` for a time window and `--limit N` for result size.
+
+Use `alerts` for notifications, unread items, starred messages, and conversation counts.
+
+Use `overview` only when the user explicitly wants multiple categories in one snapshot. A narrow request should stay on `todo` or `alerts`.
+
+## Agent Steps
+
+1. Run the narrow command.
+2. Sort or filter the returned data only when the command does not already express the request.
+3. Report exact timestamps and course/activity names; preserve the Moodle URL when it helps the user act.
+
+The branch is complete when every reported deadline or alert comes from the command result and the requested time window is explicit.

package/references/forums.md

@@ -0,0 +1,58 @@
+# Forums
+
+Read this file for forum discovery, title or body search, discussion reading, grouped forums, unread posts, or rendering checks.
+
+## Default Search
+
+Start with the narrowest high-level command:
+
+```bash
+moodle forum find QUERY --json
+```
+
+Refine it with:
+
+- `--course COURSE` to restrict the course.
+- `--forum FORUM_OR_URL` to restrict the forum.
+- `--unread-only` for unseen content.
+- `--titles-only` to avoid fetching post bodies.
+- `--list --limit N` for a shortlist.
+- `--body` only when the winning snippet is insufficient.
+- `--limit-forums N` and `--limit-discussions N` to bound large-site scans.
+
+Use `moodle forum search QUERY --json` when a larger result set is the goal. `forum find` is the default for one best answer.
+
+When one request combines search with the full matching post, use one command:
+
+```bash
+moodle forum find QUERY --course COURSE --body --json
+```
+
+Reserve `forum discussion` for an existing discussion ID or URL, or for selecting a known post ID.
+
+## Browse or Open Directly
+
+| Need | Command |
+| --- | --- |
+| List forum activities | `moodle forum forums [QUERY] --json` |
+| List discussions in one forum | `moodle forum discussions FORUM_OR_URL --json` |
+| Read a discussion | `moodle forum discussion DISCUSSION_OR_URL --json` |
+| Read one post | `moodle forum discussion DISCUSSION_OR_URL --post POST_ID --json` |
+| Include full bodies in terminal format | `moodle forum discussion DISCUSSION_OR_URL --body --table` |
+| Validate discussion rendering | `moodle forum check FORUM_OR_URL --limit 20 --json` |
+
+Skip discovery when the user already supplied a discussion URL. Use `forum discussions` when they supplied a forum view URL and want nearby threads.
+
+Grouped forums are resolved automatically. An empty default group page does not prove the forum has no discussions.
+
+## Structured Forum Content
+
+Prefer these fields over text heuristics:
+
+- `image_urls` for original images
+- `links` for extracted hyperlinks
+- `tables` for table rows and headers
+- `group_id` and `group_name` for group context
+- `unread` and `time_created` for unread/recent requests
+
+The branch is complete when the selected discussion or post matches the query and the answer retains the source URL.

package/references/maintenance.md

@@ -0,0 +1,43 @@
+# Maintenance
+
+Read this file for update checks, upgrades, agent-skill installation, or repository skill regeneration.
+
+## Update the CLI
+
+Check without changing the installation:
+
+```bash
+moodle update --check-only --json
+```
+
+Run `moodle update --table` when the user explicitly wants the installation upgraded. npm installations use `npm install -g moodle-cli@latest`; standalone binaries return the latest GitHub Release URL.
+
+If the registry check fails, verify network access and retry before proposing an upgrade command.
+
+## Install the Agent Skill
+
+Show skill metadata with:
+
+```bash
+moodle skills
+```
+
+Install from the published repository with:
+
+```bash
+moodle skills add
+```
+
+Extra arguments are passed to the shared `skills` CLI, for example `moodle skills add --agent codex`.
+
+## Regenerate the Skill Bundle
+
+Inside the `moodle-cli` source repository:
+
+```bash
+npm run build
+npm run skill:generate
+git diff -- SKILL.md references agents/openai.yaml
+```
+
+Regeneration is complete when the root skill, branch references, command reference, output contract, and agent metadata are all current.

package/references/output-and-errors.md

@@ -0,0 +1,30 @@
+# Output and Errors
+
+Read this file when choosing an output mode, filtering fields, consuming errors, or interpreting exit codes.
+
+### 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 |
+
+## Agent Handling
+
+- Parse structured stdout locally and return only the facts the user requested.
+- Treat stderr as the error channel; JSON mode emits one parseable error object there.
+- Use the exit code to distinguish authentication/configuration, usage, not-found, and unexpected failures.
+- Retry only after acting on the error hint. A repeated authentication failure needs a fresh login or session source, not another identical command.

package/references/profile-and-courses.md

@@ -0,0 +1,27 @@
+# Profile and Courses
+
+Read this file for identity, enrolled-course discovery, course sections, or course activity lists.
+
+## Choose the Command
+
+| Need | Command |
+| --- | --- |
+| Authenticated user and site | `moodle user --json` |
+| Enrolled courses | `moodle courses --json` |
+| Sections and nested activities | `moodle course COURSE --json` |
+| Flat activity list | `moodle activities COURSE --json` |
+
+`COURSE` accepts a numeric course ID or a unique course-name match. When a name could match several courses, run `moodle courses --json`, identify the intended course, and continue with its ID.
+
+## Agent Steps
+
+1. Use `user` only for account or site identity.
+2. Use `courses` for discovery and ID resolution.
+3. Use `course` when section placement matters; use `activities` when the user wants a flat inventory.
+4. Use `--fields` only for fields present in the returned objects, for example:
+
+```bash
+moodle courses --json --fields id,shortname,fullname
+```
+
+The branch is complete when the requested course or activity facts are tied to an unambiguous course ID.

package/references/setup-and-auth.md

@@ -0,0 +1,73 @@
+# Setup and Authentication
+
+Read this file for installation, first-run configuration, browser-session reuse, or authentication recovery.
+
+## Install
+
+Prefer the published npm package:
+
+```bash
+npm install -g moodle-cli
+moodle --version
+```
+
+Use `npx moodle-cli --help` for a one-off run. Existing PyPI users should migrate with:
+
+```bash
+uv tool uninstall moodle-cli
+npm install -g moodle-cli
+```
+
+Standalone binaries are available from GitHub Releases for supported platforms.
+
+## Configure the Moodle Site
+
+Set `MOODLE_BASE_URL` to the Moodle site root, such as `https://school.example.edu`. A URL ending in `/login/index.php`, `/my/`, or another page is invalid.
+
+For an interactive first run, allow the CLI to prompt for the root URL and save it under `~/.config/moodle-cli/config.yaml`.
+
+## Authenticate
+
+The CLI tries these session sources:
+
+1. `MOODLE_SESSION`
+2. A fresh local session cache
+3. Supported browser cookies
+4. `okta-auth-cli`
+
+For automatic Okta login:
+
+```bash
+uv tool install okta-auth-cli
+okta config
+```
+
+Validate setup with:
+
+```bash
+moodle user --json
+```
+
+Setup is complete when this returns the authenticated Moodle user.
+
+## Keep the Session Alive
+
+Moodle expires idle sessions server-side (often a few hours). To avoid re-running SSO logins:
+
+```bash
+moodle auth status --json              # cache freshness + server session state
+moodle auth keepalive --json           # renew once (re-login from browser/okta cookies if expired)
+moodle auth keepalive install          # macOS launch agent, renews every 30 min
+moodle auth keepalive install --interval 15
+moodle auth keepalive uninstall
+moodle auth login --json               # force a fresh login and refresh the cache
+```
+
+On Linux, schedule `moodle auth keepalive --json` with cron instead of `install`.
+
+## Recover Failures
+
+- **No usable MoodleSession**: sign in to Moodle in a supported browser and retry; otherwise configure `okta-auth-cli` or provide `MOODLE_SESSION` through the environment.
+- **Configured site is wrong**: correct `MOODLE_BASE_URL` or the saved `base_url`, then rerun `moodle user --json`.
+- **Cached session expired**: run `moodle auth login`, or rerun with `--no-cache` once so the CLI reacquires a session.
+- **Non-interactive config error**: set `MOODLE_BASE_URL`; a pipe cannot answer the first-run prompt.