@novedu/cli 0.11.0 → 0.12.1

package/README.md

@@ -1,43 +1,46 @@
 # @novedu/cli
 
 Command-line companion for the Novedu chat app (installed command: `novedu-cli`;
-requires Node >= 20). It validates every activity YAML the app accepts — **tutors**,
-**fragment libraries**, **quizzes**, **writing activities**, and **coding
-activities** — and signs in to Microsoft Entra ID (`login` / `logout` / `whoami`)
-to call the app's protected APIs; more commands will follow. Validating a tutor
-also fully validates every fragment library it references; pass `--kind` to
-validate any other kind on its own.
+requires Node >= 20). It covers two jobs:
 
-It reuses the app's exact validation pipeline (`lib/tutors`, `lib/quiz-validate`,
-`lib/writing-validate`, `lib/coding-validate`), so an activity that passes here is
-the same one the app would accept — no separate, drifting rules.
+- **Validate activity YAML** — tutors, fragment libraries, quizzes, writing
+  activities, and coding activities — with the app's exact validation pipeline,
+  offline and without signing in.
+- **Manage the app as a teacher** — sign in with Microsoft Entra ID, then mint
+  activity codes, upload app-hosted YAML files, and triage student reports,
+  straight from the terminal (or from a coding agent, see below).
 
-## Usage
+No install needed:
 
 ```bash
-# Validate a local file (relative fragment_files resolve against the file's location)
+npx @novedu/cli --help
+```
+
+## Validating activities: `validate`
+
+```bash
+# Validate a local tutor (relative fragment_files resolve against the file's location)
 npx @novedu/cli validate ./activities/examples/sorting-algorithms/sorting-tutor.yaml
 
-# Validate a published tutor by URL
+# Validate a published activity by URL
 npx @novedu/cli validate https://raw.githubusercontent.com/Teaching-HTL-Leonding/novedu-chat-mvp/refs/heads/main/activities/examples/sorting-algorithms/sorting-tutor.yaml
 
-# Validate a fragment library on its own
+# Other kinds: fragment library, quiz, writing activity, coding activity
 npx @novedu/cli validate ./activities/examples/shared/general-fragments.yaml --kind fragment
-
-# Validate a quiz, a writing activity, or a coding activity
 npx @novedu/cli validate ./activities/examples/sorting-algorithms/sorting-quiz.yaml --kind quiz
-npx @novedu/cli validate ./activities/examples/review-writing/restaurant-review-letter.yaml --kind writing
-npx @novedu/cli validate ./activities/examples/sorting-algorithms/sorting-visualizer.yaml --kind coding
 
 # Machine-readable output (the raw validation result)
-npx @novedu/cli validate ./activities/examples/sorting-algorithms/sorting-tutor.yaml --json
+npx @novedu/cli validate ./my-quiz.yaml --kind quiz --json
 ```
 
-`--kind` accepts `tutor` (default), `fragment`, `quiz`, `writing`, or `coding`; it
-is caller-declared, not auto-detected.
-
-Exit code is `0` when the activity is valid and `1` when it has errors, so it works
-as a pre-commit / CI gate.
+- `--kind` accepts `tutor` (default), `fragment`, `quiz`, `writing`, or
+  `coding`; it is caller-declared, not auto-detected.
+- The CLI reuses the app's exact validation pipeline (`lib/prompt-fragments`,
+  `lib/tutors`, `lib/quiz-validate`, `lib/writing-validate`,
+  `lib/coding-validate`), so an activity that passes here is the same one the
+  app accepts — no separate, drifting rules. Validating a tutor also fully
+  validates every fragment library it references.
+- Exit code `0` = valid, `1` = errors found — usable as a pre-commit / CI gate.
 
 ## Authentication
 
@@ -61,6 +64,9 @@ npx @novedu/cli logout   # remove the cached credentials from this machine
   file `0600`). The cache holds a refresh token, so after the one sign-in every
   command runs non-interactively; treat the file like a credential. `logout`
   is purely local — issued tokens expire on their own (~1 h).
+- `whoami` proves the full round-trip and shows your display name, user id, and
+  whether the account is a teacher (`Teacher: yes/no`) — the management
+  commands below need a teacher account.
 - The server defaults to the production app; override per command with
   `--server <url>` or the `NOVEDU_SERVER` env var (e.g.
   `http://localhost:3000` for development). Other deployments of the app can
@@ -69,6 +75,94 @@ npx @novedu/cli logout   # remove the cached credentials from this machine
 - Not signed in (or the cached token expired for good)? Commands exit 1 with
   `Not signed in — run "novedu-cli login".`
 
+## Managing codes & files (teacher account required)
+
+The `codes` and `files` groups call the app's API as the signed-in teacher. The
+server runs the identical validation pipeline as the web forms and is
+authoritative — the CLI sends your input as-is and relays the server's answer.
+
+```
+codes create --module <tutor|quiz|writing|coding> --file <url>
+             [--start <iso>] [--end <iso>] [--note <text>]
+             [--llm-provider <p> --llm-model <m>]
+codes list   [--search <q>] [--module <m>] [--all]
+files upload <name> [--kind <tutor|fragment|quiz|writing|coding>]
+             (--file <path> | reads stdin)
+files list   [--search <q>] [--all]
+```
+
+- **Output is JSON only.** Success: the API's objects verbatim on stdout, exit
+  0 (pipe into `jq`). Failure: JSON on stderr — `{ message }` or
+  `{ errors: [...] }` with the full structured validation detail — and exit 1.
+- `codes create` mints a shareable code for an activity YAML at a public URL
+  (or an app-hosted `…/api/files/<name>` URL); the YAML is validated
+  server-side before the code is stored, and the response includes the
+  shareable `url`. `--start`/`--end` must be ISO 8601 **with an explicit
+  offset or `Z`** (e.g. `2026-07-07T08:00:00Z`); the
+  `--llm-provider`/`--llm-model` override pair is both-or-nothing.
+- `files upload <name>` is an **upsert**: creating a new file requires
+  `--kind`; an existing file's kind is frozen at create time (a contradicting
+  `--kind` fails with 409). The YAML comes from `--file <path>` or stdin.
+  Every hosted file is public at the `url` the list returns — no download
+  command needed.
+- Both `list` commands default to **only your own** codes/files (like the web
+  lists); `--all` widens to every teacher's, `--search` is a contains-filter.
+
+Example — host a quiz and share it:
+
+```bash
+npx @novedu/cli files upload sorting-quiz --kind quiz --file ./sorting-quiz.yaml
+# { "name": "sorting-quiz", "kind": "quiz", "url": "https://…/api/files/sorting-quiz", "action": "created" }
+
+npx @novedu/cli codes create --module quiz \
+  --file https://…/api/files/sorting-quiz \
+  --start 2026-07-07T08:00:00Z --note "3A Monday"
+# { "code": "…", "url": "https://…/<code>", … }   — hand the url to students
+```
+
+## Triaging student reports (teacher account required)
+
+Students can flag an AI interaction — a chat or a graded quiz answer — with a
+reaction and an optional note. The `reports` group reads and resolves those
+flags; same JSON stdout/stderr contract as above.
+
+```
+reports list    [--status <open|resolved|all>] [--reaction <good|omg|bad|holysh>]
+                [--search <q>] [--all]
+reports show    <id>
+reports resolve <id...>
+```
+
+- `reports list` defaults to **open reports on your own codes** (like the web
+  inbox), most urgent first; `--all` widens to every teacher's codes.
+- `reports show <id>` prints one report in full. A **chat** report embeds the
+  conversation transcript as a `messages` array; a **quiz-answer** report
+  already carries its question / answer / feedback snapshot inline.
+- `reports resolve <id...>` resolves one or more reports in a single request;
+  unknown or already-resolved ids are silently ignored.
+- The CLI deliberately cannot file, reopen, or delete a report — those stay in
+  the web `/reports` inbox.
+
+The typical loop for turning a report into a better activity:
+
+```bash
+npx @novedu/cli reports list --reaction holysh        # find the urgent flags
+npx @novedu/cli reports show 3f2c…                    # read the report + transcript
+# fix the activity YAML, then check it offline:
+npx @novedu/cli validate ./sorting-quiz.yaml --kind quiz
+npx @novedu/cli files upload sorting-quiz --file ./sorting-quiz.yaml
+npx @novedu/cli reports resolve 3f2c…                 # existing codes already serve the fix
+```
+
+## Using the CLI from a coding agent
+
+The app repo ships a Claude Code skill that teaches coding agents the full CLI
+workflow — validation, the sign-in hand-off, code/file management, and the
+report-triage loop:
+[`.claude/skills/novedu-tutor-cli/SKILL.md`](https://github.com/Teaching-HTL-Leonding/novedu-chat-mvp/blob/main/.claude/skills/novedu-tutor-cli/SKILL.md)
+(mirrored at `.agents/skills/novedu-tutor-cli/`). Agents working inside that
+repo pick it up automatically.
+
 ## Development
 
 The CLI lives in the app repo as an npm workspace.
@@ -79,5 +173,5 @@ npm run cli:build                                    # bundle to cli/dist via ts
 npm run test:cli                                     # build + integration tests (local & live URLs)
 ```
 
-The fast in-process unit test (`cli/src/commands/validate.unit.test.ts`) runs in
-CI; the integration tests hit the network and are local-only.
+The fast in-process unit tests (`cli/src/commands/*.unit.test.ts`) run in CI;
+the integration tests hit the network and are local-only.

package/dist/main.js

@@ -249,10 +249,10 @@ async function runApiRequest(options) {
 }
 //#endregion
 //#region src/commands/codes.ts
-const SERVER_OPTION$1 = ["--server <url>", "Novedu server base URL (defaults to the NOVEDU_SERVER env var, then production)"];
+const SERVER_OPTION$2 = ["--server <url>", "Novedu server base URL (defaults to the NOVEDU_SERVER env var, then production)"];
 function registerCodes(program) {
 	const codes = program.command("codes").description("Manage activity codes on the Novedu server");
-	codes.command("create").description("Create a code for an activity YAML (validated server-side before storing)").requiredOption("--module <module>", "activity module: tutor, quiz, writing or coding").requiredOption("--file <url>", "public http(s) URL of the activity YAML").option("--start <iso>", "window start, ISO 8601 with explicit offset (e.g. 2026-07-07T08:00:00Z)").option("--end <iso>", "window end, ISO 8601 with explicit offset").option("--note <text>", "note shown in the codes list").option("--llm-provider <provider>", "LLM override provider (\"SCCH\" or \"Azure Foundry\"; needs --llm-model)").option("--llm-model <model>", "LLM override model id (needs --llm-provider)").option(...SERVER_OPTION$1).action(async (options) => {
+	codes.command("create").description("Create a code for an activity YAML (validated server-side before storing)").requiredOption("--module <module>", "activity module: tutor, quiz, writing or coding").requiredOption("--file <url>", "public http(s) URL of the activity YAML").option("--start <iso>", "window start, ISO 8601 with explicit offset (e.g. 2026-07-07T08:00:00Z)").option("--end <iso>", "window end, ISO 8601 with explicit offset").option("--note <text>", "note shown in the codes list").option("--llm-provider <provider>", "LLM override provider (\"SCCH\" or \"Azure Foundry\"; needs --llm-model)").option("--llm-model <model>", "LLM override model id (needs --llm-provider)").option(...SERVER_OPTION$2).action(async (options) => {
 		await runApiRequest({
 			server: options.server,
 			path: "/api/codes",
@@ -270,7 +270,7 @@ function registerCodes(program) {
 			}
 		});
 	});
-	codes.command("list").description("List codes (defaults to only your own, like the web list)").option("--search <q>", "contains-filter over note/code").option("--module <module>", "only codes for one activity module").option("--all", "include codes created by other teachers").option(...SERVER_OPTION$1).action(async (options) => {
+	codes.command("list").description("List codes (defaults to only your own, like the web list)").option("--search <q>", "contains-filter over note/code").option("--module <module>", "only codes for one activity module").option("--all", "include codes created by other teachers").option(...SERVER_OPTION$2).action(async (options) => {
 		const params = new URLSearchParams();
 		if (options.search) params.set("q", options.search);
 		if (options.module) params.set("module", options.module);
@@ -284,7 +284,7 @@ function registerCodes(program) {
 }
 //#endregion
 //#region src/commands/files.ts
-const SERVER_OPTION = ["--server <url>", "Novedu server base URL (defaults to the NOVEDU_SERVER env var, then production)"];
+const SERVER_OPTION$1 = ["--server <url>", "Novedu server base URL (defaults to the NOVEDU_SERVER env var, then production)"];
 async function readStdin() {
 	const chunks = [];
 	for await (const chunk of process.stdin) chunks.push(chunk);
@@ -292,7 +292,7 @@ async function readStdin() {
 }
 function registerFiles(program) {
 	const files = program.command("files").description("Manage app-hosted YAML files on the Novedu server");
-	files.command("upload <name>").description("Create or update an app-hosted YAML file from --file or stdin (validated server-side)").option("--kind <kind>", "file kind (tutor, fragment, quiz, writing, coding) — required when creating").option("--file <path>", "read the YAML from this path instead of stdin").option(...SERVER_OPTION).action(async (name, options) => {
+	files.command("upload <name>").description("Create or update an app-hosted YAML file from --file or stdin (validated server-side)").option("--kind <kind>", "file kind (tutor, fragment, quiz, writing, coding) — required when creating").option("--file <path>", "read the YAML from this path instead of stdin").option(...SERVER_OPTION$1).action(async (name, options) => {
 		let content;
 		try {
 			content = options.file === void 0 ? await readStdin() : await readFile(options.file, "utf8");
@@ -310,7 +310,7 @@ function registerFiles(program) {
 			}
 		});
 	});
-	files.command("list").description("List app-hosted YAML files (defaults to only your own, like the web list)").option("--search <q>", "contains-filter over name/title/description").option("--all", "include files last written by other teachers").option(...SERVER_OPTION).action(async (options) => {
+	files.command("list").description("List app-hosted YAML files (defaults to only your own, like the web list)").option("--search <q>", "contains-filter over name/title/description").option("--all", "include files last written by other teachers").option(...SERVER_OPTION$1).action(async (options) => {
 		const params = new URLSearchParams();
 		if (options.search) params.set("q", options.search);
 		if (options.all) params.set("mine", "0");
@@ -358,6 +358,38 @@ Purely local — already-issued access tokens stay valid until they expire
 	});
 }
 //#endregion
+//#region src/commands/reports.ts
+const SERVER_OPTION = ["--server <url>", "Novedu server base URL (defaults to the NOVEDU_SERVER env var, then production)"];
+function registerReports(program) {
+	const reports = program.command("reports").description("Triage student reports on the Novedu server");
+	reports.command("list").description("List reports (defaults to open reports on your own codes, like the web inbox)").option("--status <status>", "open (default), resolved or all").option("--reaction <reaction>", "filter by reaction: good, omg, bad or holysh").option("--search <q>", "contains-filter over description, reporter, code and note").option("--all", "include reports on codes created by other teachers").option(...SERVER_OPTION).action(async (options) => {
+		const params = new URLSearchParams();
+		if (options.status) params.set("status", options.status);
+		if (options.reaction) params.set("reaction", options.reaction);
+		if (options.search) params.set("q", options.search);
+		if (options.all) params.set("mine", "0");
+		const query = params.toString();
+		await runApiRequest({
+			server: options.server,
+			path: `/api/reports${query ? `?${query}` : ""}`
+		});
+	});
+	reports.command("show <id>").description("Show one report; a chat report embeds its conversation transcript").option(...SERVER_OPTION).action(async (id, options) => {
+		await runApiRequest({
+			server: options.server,
+			path: `/api/reports/${encodeURIComponent(id)}`
+		});
+	});
+	reports.command("resolve <id...>").description("Resolve one or more reports by id (bulk, in a single request)").option(...SERVER_OPTION).action(async (ids, options) => {
+		await runApiRequest({
+			server: options.server,
+			path: "/api/reports/resolve",
+			method: "POST",
+			body: { ids }
+		});
+	});
+}
+//#endregion
 //#region ../lib/prompt-fragments/assemble.ts
 const COMPILE_OPTIONS = {
 	strict: true,
@@ -1705,6 +1737,7 @@ registerLogout(program);
 registerWhoami(program);
 registerCodes(program);
 registerFiles(program);
+registerReports(program);
 program.parseAsync().catch((err) => {
 	console.error(err instanceof Error ? err.message : err);
 	process.exitCode = 1;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@novedu/cli",
-  "version": "0.11.0",
+  "version": "0.12.1",
   "description": "Command-line companion for the Novedu chat app. Validates tutor, fragment, quiz, writing and coding YAML definitions; signs in with Entra ID and manages codes and app-hosted files over the app's API.",
   "type": "module",
   "repository": {