moodle-cli 0.5.5 → 0.7.0-alpha.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "moodle-cli",
-  "version": "0.5.5",
+  "version": "0.7.0-alpha.0",
   "description": "Terminal-first CLI for Moodle LMS",
   "license": "MIT",
   "type": "module",
@@ -10,36 +10,42 @@
   "files": [
     "dist",
     "README.md",
+    "ONBOARDING.md",
     "SKILL.md",
+    "references",
+    "agents",
     "LICENSE"
   ],
   "scripts": {
-    "build": "tsup && rm -f dist/.gitignore",
+    "build": "tsc --noEmit && tsup && npm run build:worker && rm -f dist/.gitignore",
+    "build:worker": "tsup --config tsup.worker.config.ts && node scripts/check-worker-bundle.mjs",
     "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: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\")\"",
+    "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', 'dist/worker/worker.js', 'README.md', 'ONBOARDING.md', 'SKILL.md', 'references/command-reference.md', 'references/downloads.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\")\" && \"$tmp/install/node_modules/.bin/moodle\" download --help >/dev/null && \"$tmp/install/node_modules/.bin/moodle\" mcp --help >/dev/null",
     "test": "vitest run",
+    "test:mcp": "vitest run tests/mcp-*.test.ts tests/deployment-*.test.ts tests/renewal-*.test.ts tests/connectors-*.test.ts",
+    "test:worker": "vitest run tests/worker-*.test.ts",
     "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 && npm run pack:check"
   },
   "dependencies": {
-    "commander": "^14.0.0",
+    "@bunizao/cli-kit": "^0.1.0",
+    "@steipete/sweet-cookie": "^0.4.0",
+    "commander": "^13.1.0",
     "node-html-parser": "^7.0.1",
+    "wrangler": "^4.120.0",
     "yaml": "^2.8.0",
     "zod": "^4.0.5"
   },
-  "optionalDependencies": {
-    "chrome-cookies-secure": "^3.0.2"
-  },
   "devDependencies": {
     "@types/node": "^24.0.10",
     "tsup": "^8.5.0",
-    "typescript": "^5.8.3",
+    "typescript": "^7.0.2",
     "vitest": "^3.2.4"
   },
   "engines": {
-    "node": ">=20"
+    "node": ">=22"
   },
   "repository": {
     "type": "git",

package/references/command-reference.md

@@ -0,0 +1,48 @@
+# Command Reference
+
+Read this file for exact arguments, flags, and defaults after selecting a branch from `SKILL.md`.
+
+| Command | Description | Arguments | Flags |
+| --- | --- | --- | --- |
+| moodle activities | Inspect activities. |  |  |
+| moodle activities list | List activities in a unit. | <unit> | --json<br>--yaml<br>--table<br>--fields (value required) |
+| moodle activities show | Show activity detail. | <id> | --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 (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 | Extract a fresh session, opening the browser when needed. |  | --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 commands | Describe the complete command tree. |  | --json<br>--yaml<br>--table<br>--fields (value required) |
+| moodle download | Download one authenticated Moodle file. | <source> | --dest (value required)<br>--force<br>--json<br>--yaml<br>--table<br>--fields (value required) |
+| moodle forums | Inspect forums. |  |  |
+| moodle forums list | List forum activities in a unit. | <unit> | --json<br>--yaml<br>--table<br>--fields (value required)<br>--limit (value required) |
+| moodle forums 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 (value required) |
+| moodle forums show | List discussions from a forum. | <forum> | --json<br>--yaml<br>--table<br>--fields (value required)<br>--limit (value required)<br>--query (value required) |
+| moodle grades | Inspect grades. |  |  |
+| moodle grades list | Show grade details for a unit. | <unit> | --json<br>--yaml<br>--table<br>--fields (value required) |
+| moodle mcp | Deploy and manage a private Moodle MCP server. |  |  |
+| moodle mcp bridge | Bridge a stdio MCP client to the managed remote server. |  | --profile (value required) |
+| moodle mcp connect | Connect a supported MCP client. | [client] | --json<br>--yaml<br>--table<br>--fields (value required)<br>--mode (value required)<br>--show-token |
+| moodle mcp deploy | Deploy or update the managed Moodle MCP server. |  | --json<br>--yaml<br>--table<br>--fields (value required)<br>--dry-run<br>--repair<br>--rotate-token<br>--rollback |
+| moodle mcp login | Acquire and upload a fresh Moodle session. |  | --json<br>--yaml<br>--table<br>--fields (value required) |
+| moodle mcp remove | Remove one managed Moodle MCP deployment. |  | --json<br>--yaml<br>--table<br>--fields (value required) |
+| moodle mcp renewal | Run the installed managed-session renewal job. |  |  |
+| moodle mcp renewal run | Check and renew one managed Moodle session. |  | --json<br>--yaml<br>--table<br>--fields (value required)<br>--profile (value required) |
+| moodle mcp serve | Run the local Moodle MCP server. |  | --stdio |
+| moodle mcp session | Advanced managed-session operations. |  |  |
+| moodle mcp session push | Upload a Moodle cookie from standard input. |  | --stdin<br>--json<br>--yaml<br>--table<br>--fields (value required) |
+| moodle mcp status | Show local and remote Moodle MCP readiness. |  | --json<br>--yaml<br>--table<br>--fields (value required)<br>--verbose<br>--logs |
+| moodle overview | Show a compact multi-source overview. |  | --json<br>--yaml<br>--table<br>--fields (value required)<br>--todo-limit (value required)<br>--todo-days (value required)<br>--alerts-limit (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 threads | Inspect forum discussion threads. |  |  |
+| moodle threads show | Show posts in a forum discussion. | <discussion> | --json<br>--yaml<br>--table<br>--fields (value required)<br>--post (value required)<br>--body |
+| moodle todo | List upcoming actionable timeline items. |  | --json<br>--yaml<br>--table<br>--fields (value required)<br>--limit (value required)<br>--days (value required) |
+| moodle units | Inspect enrolled units. |  |  |
+| moodle units list | List enrolled units. |  | --json<br>--yaml<br>--table<br>--fields (value required) |
+| moodle units show | Show unit detail with sections. | <unit> | --json<br>--yaml<br>--table<br>--fields (value required) |
+| moodle user | Show authenticated user info. |  | --json<br>--yaml<br>--table<br>--fields (value required) |

package/references/coursework-and-grades.md

@@ -0,0 +1,45 @@
+# 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 UNIT --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 |
+| --- | --- |
+All supported activity types share the course-module ID namespace and use one command:
+
+```bash
+moodle activities show ACTIVITY_ID --json
+```
+
+The result includes `type` (`assign`, `quiz`, `resource`, `link`, `page`, or `folder`).
+
+Resource and folder details include `file_entries` with a filename, authenticated URL, and authentication requirement. When the user wants local files, continue with [downloads.md](downloads.md) instead of fetching those URLs outside the CLI.
+
+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 `file_entries` 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/downloads.md

@@ -0,0 +1,38 @@
+# Local File Downloads
+
+Read this file when the user wants one or more Moodle files saved locally. The canonical command is `moodle download`; `moodle dl` is an optional alias.
+
+## One Resource
+
+When the caller has an activity but not a direct file URL, inspect it first:
+
+```bash
+moodle activities show ACTIVITY_ID --json
+```
+
+For one resource, pass its positive course-module ID, same-site resource URL, or same-site `pluginfile.php` URL:
+
+```bash
+moodle download ACTIVITY_ID --dest './Course/Week 03/slides.pdf' --json
+moodle download 'MOODLE_RESOURCE_URL' --dest './Course/Week 03/slides.pdf' --json
+```
+
+`--dest` is the exact downloaded file path. Without it, the CLI writes the upstream filename in the current directory. Existing files are preserved by default.
+
+## Folder Files
+
+The CLI does not recursively download a Moodle folder. Inspect the folder, select the relevant `file_entries`, plan each destination, and invoke `moodle download` separately for every chosen URL:
+
+```bash
+moodle activities show FOLDER_ACTIVITY_ID --json
+moodle download 'FILE_ENTRY_URL' --dest './Course/Week 03/chapter-1.pdf' --json
+```
+
+Treat every `file_entries.url` as authenticated Moodle data. Use it only through the CLI and never expose Moodle cookies, sesskeys, or other credentials.
+
+## Replacement and Verification
+
+- Preserve an existing destination unless the user explicitly authorized replacement or you independently verified that replacing that exact path is safe.
+- Add `--force` only for that verified replacement. It atomically replaces the completed destination; downloads do not use `--yes`.
+- Keep `-o/--output` separate from `--dest`: output selects where the receipt is written, while destination selects the downloaded file.
+- Validate the receipt fields, confirm `file_path` exists, and verify the saved file is non-empty and not a Moodle login page or unresolved resource wrapper. Command success alone is not proof of valid file content.

package/references/forums.md

@@ -0,0 +1,57 @@
+# 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 forums search 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 forums search QUERY --json` and narrow with `--limit` when only a few matches are needed.
+
+When one request combines search with the full matching post, use one command:
+
+```bash
+moodle forums search QUERY --course UNIT --limit 1 --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 forums UNIT --json` |
+| List discussions in one forum | `moodle forums show FORUM_OR_URL --json` |
+| Read a discussion | `moodle threads show DISCUSSION_OR_URL --json` |
+| Read one post | `moodle threads show DISCUSSION_OR_URL --post POST_ID --json` |
+| Include full bodies in terminal format | `moodle threads show DISCUSSION_OR_URL --body --table` |
+
+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,31 @@
+# Maintenance
+
+Read this file for CLI upgrades or agent-skill installation.
+
+## Update the CLI
+
+Check the npm registry without changing the installation:
+
+```bash
+npm view moodle-cli version
+```
+
+Upgrade an npm installation with `npm install -g moodle-cli@latest`. Standalone binaries are available from GitHub Releases.
+
+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`.

package/references/output-and-errors.md

@@ -0,0 +1,31 @@
+# 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.
+- Structured errors use `{ok:false,error:{code,message,hint},exit_code}` on stderr.
+
+Exit codes:
+
+| Code | Meaning |
+| --- | --- |
+| 0 | Success |
+| 1 | Network, configuration, or unexpected error |
+| 2 | Usage error |
+| 3 | Authentication error |
+| 4 | Requested course, activity, forum, or discussion was not found |
+| 5 | Moodle rejected a well-formed request |
+
+## 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 units | `moodle units --json` |
+| Sections and nested activities | `moodle units show UNIT --json` |
+| Flat activity list | `moodle activities UNIT --json` |
+
+`UNIT` accepts a numeric ID or a unique name match. When a name could match several units, run `moodle units --json`, identify the intended unit, and continue with its ID.
+
+## Agent Steps
+
+1. Use `user` only for account or site identity.
+2. Use `units` 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 units --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,91 @@
+# 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               # extract a session; open the browser if needed
+```
+
+On Linux, schedule `moodle auth keepalive --json` with cron instead of `install`.
+
+`moodle auth login` first checks local session sources. If none is valid, it opens Moodle's login page in the system browser and waits up to two minutes for the completed SSO/OAuth login.
+
+## 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.
+
+## Manage the Private MCP Server
+
+Use the lifecycle commands instead of asking the user to copy cookies, tokens, Wrangler commands, or client configuration:
+
+```bash
+moodle mcp deploy
+moodle mcp status --json
+moodle mcp login
+moodle mcp connect
+moodle mcp remove
+```
+
+`moodle mcp deploy` validates the local Moodle session, deploys and verifies a private Cloudflare Worker, installs local renewal, and connects detected clients. The default bridge mode keeps the Bearer token out of client files. Use `moodle mcp login` when status reports `SESSION_EXPIRED`; use `moodle mcp deploy --repair` when Cloudflare authorization or managed deployment state needs repair.
+
+Never print or request the raw Moodle cookie, MCP access token, session sync token, or sesskey. An advanced operator may pipe a cookie directly to `moodle mcp session push --stdin`; do not place it in arguments or shell history.