moodle-cli 0.5.5

package/LICENSE

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

package/README.md

@@ -0,0 +1,155 @@
+# moodle-cli
+
+Terminal-first CLI for Moodle LMS that reuses an authenticated browser session. No Moodle API token required.
+
+## Features
+
+- Reuses `MoodleSession` from `okta-auth`, your browser, or `MOODLE_SESSION`
+- Uses Moodle AJAX APIs and falls back to authenticated page scraping when needed
+- Lists courses, deadlines, alerts, activities, grades, and forum discussions
+- Agent-friendly JSON/YAML output, field selection, and stable exit codes
+
+## Install
+
+```bash
+npm i -g moodle-cli
+```
+
+Run without installing:
+
+```bash
+npx moodle-cli --help
+```
+
+Standalone binaries are attached to GitHub Releases for macOS arm64 and Linux x64.
+
+### Existing PyPI Users
+
+The TypeScript CLI keeps the same config file and environment variables as the Python package. Migrate with:
+
+```bash
+uv tool uninstall moodle-cli
+npm i -g moodle-cli
+```
+
+`~/.config/moodle-cli/config.yaml`, `MOODLE_BASE_URL`, and `MOODLE_SESSION` remain compatible.
+
+## Authentication
+
+Use one of:
+
+- `okta-auth-cli` configured for your Moodle site
+- an active Moodle browser session
+- a `MOODLE_SESSION` environment variable
+
+Optional Okta setup:
+
+```bash
+npm i -g okta-auth-cli
+okta config
+```
+
+On first run, if no `base_url` is configured, the CLI prompts for the Moodle root URL and saves it to `~/.config/moodle-cli/config.yaml`:
+
+```yaml
+base_url: https://school.example.edu
+```
+
+Use a root URL only, not `/login/index.php` or `/my/`.
+
+## Usage
+
+```bash
+moodle --help
+moodle user
+moodle alerts
+moodle todo
+moodle overview
+moodle courses
+moodle grades 34637
+moodle activities 34637
+moodle https://school.example.edu/course/view.php?id=34637
+moodle https://school.example.edu/mod/forum/discuss.php?d=9001#p9101 --json
+moodle skills
+moodle skills generate
+moodle skills add
+moodle update
+moodle update --check-only
+```
+
+Supported Moodle URLs can be passed as the first argument. The CLI routes forum discussion, forum view, assignment, quiz, resource, link, page, folder, course, and grade report URLs to the shortest matching command.
+
+## Agent Output Contract
+
+JSON-capable commands support:
+
+- `--json`: write JSON to stdout
+- `--yaml`: write YAML to stdout
+- `--table`: force human output
+- `--fields a,b,c`: keep only listed top-level fields; arrays apply the filter per item
+
+When stdout is not a TTY, the CLI defaults to JSON. `--table` overrides that.
+
+Invalid `--fields` values fail as usage errors and list valid fields.
+
+With JSON output enabled, errors are one parseable JSON line on stderr:
+
+```json
+{"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 |
+
+## Updates
+
+```bash
+moodle update --check-only
+moodle update --json
+```
+
+`moodle update` checks `https://registry.npmjs.org/moodle-cli/latest`. npm installs update with:
+
+```bash
+npm install -g moodle-cli@latest
+```
+
+Standalone binaries print the latest GitHub Release URL instead of modifying themselves.
+
+## Agent Skill
+
+Install the bundled agent skill:
+
+```bash
+npx skills add https://github.com/bunizao/moodle-cli
+```
+
+The CLI alias delegates to the same command:
+
+```bash
+moodle skills add
+```
+
+Regenerate `SKILL.md` from the command tree:
+
+```bash
+npm run build
+npm run skill:generate
+git diff --exit-code SKILL.md
+```
+
+## Development
+
+```bash
+npm install
+npm run check
+npm test
+npm run build
+```

package/SKILL.md

@@ -0,0 +1,167 @@
+---
+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.
+---
+
+# moodle-cli
+
+<!-- Generated by `moodle skills generate`. Edit `src/skill.template.md` for prose changes. -->
+
+Use `moodle` for read-only Moodle access.
+
+## Defaults
+
+Use the narrowest command that answers the request.
+
+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.
+
+Omit `--json` only when a human explicitly wants the formatted terminal view. Use `--table` to force human output in a pipe.
+
+Resolve course IDs with `moodle courses --json` before running course-specific commands when the user gives only a course name.
+
+Avoid `moodle overview --json` unless the user explicitly asks for a combined snapshot across courses, deadlines, and alerts.
+
+## 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.