moodle-cli 0.6.0 → 0.7.0-alpha.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "moodle-cli",
-  "version": "0.6.0",
+  "version": "0.7.0-alpha.1",
   "description": "Terminal-first CLI for Moodle LMS",
   "license": "MIT",
   "type": "module",
@@ -10,30 +10,35 @@
   "files": [
     "dist",
     "README.md",
+    "ONBOARDING.md",
     "SKILL.md",
     "references",
     "agents",
     "LICENSE"
   ],
   "scripts": {
-    "build": "tsc --noEmit && 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",
+    "bin:smoke": "bun scripts/smoke-standalone.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) ?? []; 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\")\"",
+    "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 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",
@@ -41,7 +46,7 @@
     "vitest": "^3.2.4"
   },
   "engines": {
-    "node": ">=20"
+    "node": ">=22"
   },
   "repository": {
     "type": "git",

package/references/command-reference.md

@@ -4,35 +4,45 @@ Read this file for exact arguments, flags, and defaults after selecting a branch
 
 | 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 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 | Force a fresh login and refresh the session cache. |  | --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 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 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 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 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

@@ -7,7 +7,7 @@ Read this file for grades or detail about assignments, quizzes, resources, links
 Use a course ID or unique course name:
 
 ```bash
-moodle grades COURSE --json
+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.
@@ -18,12 +18,15 @@ 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` |
+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:
 
@@ -37,6 +40,6 @@ The CLI recognizes course, grade report, forum, assignment, quiz, resource, link
 
 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.
+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/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

@@ -7,7 +7,7 @@ Read this file for forum discovery, title or body search, discussion reading, gr
 Start with the narrowest high-level command:
 
 ```bash
-moodle forum find QUERY --json
+moodle forums search QUERY --json
 ```
 
 Refine it with:
@@ -20,12 +20,12 @@ Refine it with:
 - `--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.
+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 forum find QUERY --course COURSE --body --json
+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.
@@ -34,12 +34,11 @@ Reserve `forum discussion` for an existing discussion ID or URL, or for selectin
 
 | 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` |
+| 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.
 

package/references/maintenance.md

@@ -1,16 +1,16 @@
 # Maintenance
 
-Read this file for update checks, upgrades, agent-skill installation, or repository skill regeneration.
+Read this file for CLI upgrades or agent-skill installation.
 
 ## Update the CLI
 
-Check without changing the installation:
+Check the npm registry without changing the installation:
 
 ```bash
-moodle update --check-only --json
+npm view moodle-cli version
 ```
 
-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.
+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.
 
@@ -29,15 +29,3 @@ 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

@@ -10,17 +10,18 @@ Read this file when choosing an output mode, filtering fields, consuming errors,
 - 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":"..."}`.
+- Structured errors use `{ok:false,error:{code,message,hint},exit_code}` on stderr.
 
 Exit codes:
 
 | Code | Meaning |
 | --- | --- |
 | 0 | Success |
-| 1 | Unexpected error |
-| 2 | Authentication or configuration error |
-| 3 | Usage error |
+| 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
 

package/references/profile-and-courses.md

@@ -7,21 +7,21 @@ Read this file for identity, enrolled-course discovery, course sections, or cour
 | 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` |
+| Enrolled units | `moodle units --json` |
+| Sections and nested activities | `moodle units show UNIT --json` |
+| Flat activity list | `moodle activities UNIT --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.
+`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 `courses` for discovery and ID resolution.
+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 courses --json --fields id,shortname,fullname
+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

@@ -60,14 +60,32 @@ moodle auth keepalive --json           # renew once (re-login from browser/okta
 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
+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.