@novedu/cli 0.6.0 → 0.8.0

package/README.md

@@ -1,10 +1,12 @@
 # @novedu/cli
 
-Command-line companion for the Novedu chat app (installed command: `novedu-cli`).
-Today it validates every activity YAML the app accepts — **tutors**, **fragment
-libraries**, **quizzes**, **writing activities**, and **coding activities**; 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.
+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.
 
 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
@@ -13,22 +15,22 @@ the same one the app would accept — no separate, drifting rules.
 ## Usage
 
 ```bash
-# Validate a local file (relative fragment_files resolve from the same folder)
-npx @novedu/cli validate ./activities/tutors/simple-tutor.yaml
+# Validate a local file (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
-npx @novedu/cli validate https://raw.githubusercontent.com/Teaching-HTL-Leonding/novedu-chat-mvp/refs/heads/main/activities/tutors/simple-tutor.yaml
+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
-npx @novedu/cli validate ./activities/tutors/simple-fragments.yaml --kind fragment
+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/quizzes/sample-quiz.yaml --kind quiz
-npx @novedu/cli validate ./activities/writings/human-animal-short-story.yaml --kind writing
-npx @novedu/cli validate ./activities/coding/beginner-typescript.yaml --kind coding
+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/tutors/simple-tutor.yaml --json
+npx @novedu/cli validate ./activities/examples/sorting-algorithms/sorting-tutor.yaml --json
 ```
 
 `--kind` accepts `tutor` (default), `fragment`, `quiz`, `writing`, or `coding`; it
@@ -37,12 +39,42 @@ 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.
 
+## Authentication
+
+Commands that talk to the running app authenticate with Microsoft Entra ID:
+
+```bash
+npx @novedu/cli login    # opens your browser for the Microsoft sign-in
+npx @novedu/cli whoami   # verify: calls the app's GET /api/me with your token
+npx @novedu/cli logout   # remove the cached credentials from this machine
+```
+
+- `login` opens a browser window for the Microsoft sign-in (and prints the URL
+  as a fallback). **First-time users see a one-time consent prompt** ("Access
+  Novedu APIs from the CLI") — accept it once and it never reappears. When
+  already signed in, `login` just says so and exits.
+- On a machine without a browser, `login --device-code` prints a verification
+  URL and a code to enter from any other device. Note that tenants commonly
+  block the device code flow by Conditional Access policy (error 53003) — the
+  default browser flow is not affected.
+- Credentials are cached in `~/.novedu/token-cache.json` (directory `0700`,
+  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).
+- 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
+  point the CLI at their own tenant/app registration via `NOVEDU_TENANT_ID` /
+  `NOVEDU_CLIENT_ID`.
+- Not signed in (or the cached token expired for good)? Commands exit 1 with
+  `Not signed in — run "novedu-cli login".`
+
 ## Development
 
 The CLI lives in the app repo as an npm workspace.
 
 ```bash
-npm run cli -- validate ./activities/tutors/simple-tutor.yaml   # run from source via tsx
+npm run cli -- validate ./activities/examples/sorting-algorithms/sorting-tutor.yaml   # run from source via tsx
 npm run cli:build                                    # bundle to cli/dist via tsdown
 npm run test:cli                                     # build + integration tests (local & live URLs)
 ```

package/dist/main.js

@@ -1,12 +1,363 @@
 #!/usr/bin/env node
-import { readFileSync } from "node:fs";
+import { mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { Command } from "commander";
-import { resolve } from "node:path";
+import { spawn } from "node:child_process";
+import { createServer } from "node:http";
+import { homedir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+import { CryptoProvider, PublicClientApplication } from "@azure/msal-node";
+import { readFile } from "node:fs/promises";
 import { fileURLToPath, pathToFileURL } from "node:url";
 import Handlebars from "handlebars";
 import { parse } from "yaml";
 import { z } from "zod";
-import { readFile } from "node:fs/promises";
+//#region src/auth.ts
+const DEFAULT_TENANT_ID = "91fc072c-edef-4f97-bdc5-cfb67718ae3a";
+const DEFAULT_CLIENT_ID = "4d44fc4b-0434-4981-9765-62e2074ceecb";
+function tenantId() {
+	return process.env.NOVEDU_TENANT_ID || DEFAULT_TENANT_ID;
+}
+function clientId() {
+	return process.env.NOVEDU_CLIENT_ID || DEFAULT_CLIENT_ID;
+}
+/** The delegated scope every token is requested for; msal-node adds the OIDC scopes itself. */
+function scopes() {
+	return [`api://${clientId()}/cli.access`];
+}
+const TOKEN_CACHE_PATH = join(join(homedir(), ".novedu"), "token-cache.json");
+/** Thrown when a command needs a token but no (usable) cached account exists. */
+var NotSignedInError = class extends Error {
+	constructor() {
+		super("Not signed in — run \"novedu-cli login\".");
+		this.name = "NotSignedInError";
+	}
+};
+/**
+* File-backed MSAL cache (az-CLI model): plain JSON, directory 0700, file
+* 0600. A missing file simply means an empty cache. Exported for tests.
+*/
+function buildCachePlugin(cachePath = TOKEN_CACHE_PATH) {
+	const cacheDir = dirname(cachePath);
+	return {
+		beforeCacheAccess: async (context) => {
+			let data;
+			try {
+				data = readFileSync(cachePath, "utf8");
+			} catch {
+				return;
+			}
+			context.tokenCache.deserialize(data);
+		},
+		afterCacheAccess: async (context) => {
+			if (!context.cacheHasChanged) return;
+			mkdirSync(cacheDir, {
+				recursive: true,
+				mode: 448
+			});
+			writeFileSync(cachePath, context.tokenCache.serialize(), { mode: 384 });
+		}
+	};
+}
+function buildPca(cachePath = TOKEN_CACHE_PATH) {
+	return new PublicClientApplication({
+		auth: {
+			clientId: clientId(),
+			authority: `https://login.microsoftonline.com/${tenantId()}`
+		},
+		cache: { cachePlugin: buildCachePlugin(cachePath) }
+	});
+}
+/**
+* Acquires a token silently from the cached account (MSAL refreshes via the
+* cached refresh token when needed). Returns null when there is no account or
+* the silent acquisition fails (expired/revoked refresh token) — callers
+* decide between falling back to interactive (`login`) and NotSignedInError.
+*/
+async function acquireSilent(pca) {
+	const [account] = await pca.getTokenCache().getAllAccounts();
+	if (!account) return null;
+	try {
+		return await pca.acquireTokenSilent({
+			account,
+			scopes: scopes()
+		});
+	} catch {
+		return null;
+	}
+}
+function defaultOpenBrowser(url) {
+	const [command, args] = process.platform === "darwin" ? ["open", [url]] : process.platform === "win32" ? ["cmd", [
+		"/c",
+		"start",
+		"",
+		url
+	]] : ["xdg-open", [url]];
+	try {
+		spawn(command, args, {
+			stdio: "ignore",
+			detached: true
+		}).unref();
+	} catch {}
+}
+/**
+* Runs the interactive authorization-code + PKCE flow with a loopback
+* redirect (the az-CLI model): opens the system browser and receives the code
+* on a short-lived localhost server. This is the DEFAULT login flow — tenant
+* Conditional Access policies commonly block the device code flow (error
+* 53003) but permit this one, since it is the same flow the web sign-in uses.
+*
+* Entra matches any localhost port against the registered `http://localhost`
+* public-client redirect URI, so the receiver binds an ephemeral port.
+* `onUrl` always receives the sign-in URL (fallback when no browser opens).
+*/
+async function acquireInteractive(pca, onUrl, openBrowser = defaultOpenBrowser) {
+	const { verifier, challenge } = await new CryptoProvider().generatePkceCodes();
+	const server = createServer();
+	const redirectUri = `http://localhost:${await new Promise((resolve, reject) => {
+		server.once("error", reject);
+		server.listen(0, () => resolve(server.address().port));
+	})}`;
+	try {
+		const authCode = new Promise((resolve, reject) => {
+			const timeout = setTimeout(() => reject(/* @__PURE__ */ new Error("Sign-in timed out after 5 minutes.")), 5 * 6e4);
+			server.on("request", (req, res) => {
+				const url = new URL(req.url ?? "/", redirectUri);
+				const code = url.searchParams.get("code");
+				const error = url.searchParams.get("error");
+				if (!code && !error) {
+					res.writeHead(404);
+					res.end();
+					return;
+				}
+				res.writeHead(200, { "content-type": "text/html; charset=utf-8" });
+				res.end(code ? "<p>Signed in — you can close this tab and return to the terminal.</p>" : "<p>Sign-in failed — you can close this tab.</p>");
+				clearTimeout(timeout);
+				if (code) resolve(code);
+				else reject(/* @__PURE__ */ new Error(`Sign-in failed: ${url.searchParams.get("error_description") ?? error}`));
+			});
+		});
+		const authUrl = await pca.getAuthCodeUrl({
+			scopes: scopes(),
+			redirectUri,
+			codeChallenge: challenge,
+			codeChallengeMethod: "S256"
+		});
+		onUrl(authUrl);
+		openBrowser(authUrl);
+		const code = await authCode;
+		return await pca.acquireTokenByCode({
+			code,
+			scopes: scopes(),
+			redirectUri,
+			codeVerifier: verifier
+		});
+	} finally {
+		server.close();
+	}
+}
+/**
+* Runs the device code flow — for machines without a local browser; the
+* tenant's Conditional Access policy must allow it. `onMessage` receives
+* Entra's instruction line (verification URL + user code) the moment the flow
+* starts — print it immediately so it can be relayed to the human while MSAL
+* keeps polling.
+*/
+async function acquireByDeviceCode(pca, onMessage) {
+	const result = await pca.acquireTokenByDeviceCode({
+		deviceCodeCallback: (response) => onMessage(response.message),
+		scopes: scopes()
+	});
+	if (!result) throw new Error("Device code sign-in did not return a token.");
+	return result;
+}
+/**
+* The one call every API command makes: a silently-acquired access token for
+* the Authorization header. Throws NotSignedInError when interactive login is
+* required first.
+*/
+async function getAccessToken() {
+	const result = await acquireSilent(buildPca());
+	if (!result) throw new NotSignedInError();
+	return result.accessToken;
+}
+/** Human-readable account label for command output. */
+function displayName(result) {
+	return result.account?.name ?? result.account?.username ?? "(unknown account)";
+}
+//#endregion
+//#region src/server-url.ts
+const DEFAULT_SERVER = "https://novedu-chat-mvp-at.azurewebsites.net";
+function resolveServerUrl(cliOption) {
+	return cliOption || process.env.NOVEDU_SERVER || DEFAULT_SERVER;
+}
+//#endregion
+//#region src/api.ts
+/** Pretty-prints a success payload to stdout. */
+function printJson(value) {
+	console.log(JSON.stringify(value, null, 2));
+}
+/** Prints a failure payload as JSON to stderr and marks the process failed. */
+function failJson(value) {
+	console.error(JSON.stringify(value, null, 2));
+	process.exitCode = 1;
+}
+/**
+* Performs one authenticated API request and prints the outcome per the JSON
+* contract. Server error bodies (`{ message }` — incl. the generic 401/403 —
+* or `{ errors }`) are passed through VERBATIM to stderr — the server's
+* structured validation detail is the CLI's error message. No client-side
+* pre-validation: the server runs the identical pipeline; offline checking is
+* the `validate` command's job.
+*/
+async function runApiRequest(options) {
+	let token;
+	try {
+		token = await getAccessToken();
+	} catch (error) {
+		if (error instanceof NotSignedInError) {
+			failJson({ message: error.message });
+			return;
+		}
+		throw error;
+	}
+	const server = resolveServerUrl(options.server);
+	let response;
+	try {
+		response = await fetch(new URL(options.path, server), {
+			method: options.method ?? "GET",
+			headers: {
+				authorization: `Bearer ${token}`,
+				...options.body === void 0 ? {} : { "content-type": "application/json" }
+			},
+			body: options.body === void 0 ? void 0 : JSON.stringify(options.body)
+		});
+	} catch (error) {
+		failJson({ message: `Could not reach ${server}: ${error instanceof Error ? error.message : error}` });
+		return;
+	}
+	let payload;
+	try {
+		payload = await response.json();
+	} catch {
+		payload = void 0;
+	}
+	if (!response.ok) {
+		failJson(payload ?? { message: `${server} rejected the request: HTTP ${response.status}` });
+		return;
+	}
+	printJson(payload ?? null);
+}
+//#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)"];
+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) => {
+		await runApiRequest({
+			server: options.server,
+			path: "/api/codes",
+			method: "POST",
+			body: {
+				module: options.module,
+				fileUrl: options.file,
+				...options.start === void 0 ? {} : { validFrom: options.start },
+				...options.end === void 0 ? {} : { validUntil: options.end },
+				...options.note === void 0 ? {} : { note: options.note },
+				...options.llmProvider === void 0 && options.llmModel === void 0 ? {} : { llm: {
+					provider: options.llmProvider ?? "",
+					model: options.llmModel ?? ""
+				} }
+			}
+		});
+	});
+	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) => {
+		const params = new URLSearchParams();
+		if (options.search) params.set("q", options.search);
+		if (options.module) params.set("module", options.module);
+		if (options.all) params.set("mine", "0");
+		const query = params.toString();
+		await runApiRequest({
+			server: options.server,
+			path: `/api/codes${query ? `?${query}` : ""}`
+		});
+	});
+}
+//#endregion
+//#region src/commands/files.ts
+const SERVER_OPTION = ["--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);
+	return Buffer.concat(chunks).toString("utf8");
+}
+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) => {
+		let content;
+		try {
+			content = options.file === void 0 ? await readStdin() : await readFile(options.file, "utf8");
+		} catch (error) {
+			failJson({ message: `Could not read ${options.file}: ${error instanceof Error ? error.message : error}` });
+			return;
+		}
+		await runApiRequest({
+			server: options.server,
+			path: `/api/files/${encodeURIComponent(name)}`,
+			method: "PUT",
+			body: {
+				...options.kind === void 0 ? {} : { kind: options.kind },
+				content
+			}
+		});
+	});
+	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) => {
+		const params = new URLSearchParams();
+		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/files${query ? `?${query}` : ""}`
+		});
+	});
+}
+//#endregion
+//#region src/commands/login.ts
+function registerLogin(program) {
+	program.command("login").description("Sign in to Microsoft Entra ID (opens your browser)").option("--device-code", "sign in with the device code flow instead (for machines without a browser; the tenant must allow it)").addHelpText("after", `
+Sign-in is the one human-assisted step: by default a browser window opens for
+the Microsoft sign-in (first-time users see a one-time consent prompt). On a
+machine without a browser, --device-code prints a verification URL and a code
+to enter from any other device — note that some tenants block the device code
+flow by policy (error 53003). Every other command then works non-interactively
+from the cached credentials. Already signed in? The command says so and exits
+— it never blocks.`).action(async (options) => {
+		const pca = buildPca();
+		const cached = await acquireSilent(pca);
+		if (cached) {
+			console.log(`Already signed in as ${displayName(cached)}.`);
+			return;
+		}
+		const result = options.deviceCode ? await acquireByDeviceCode(pca, (message) => console.log(message)) : await acquireInteractive(pca, (url) => {
+			console.log("A browser window should open for the Microsoft sign-in.");
+			console.log(`If it does not, open this URL yourself:\n${url}`);
+		});
+		console.log(`Signed in as ${displayName(result)}.`);
+	});
+}
+//#endregion
+//#region src/commands/logout.ts
+function registerLogout(program) {
+	program.command("logout").description("Sign out: remove the cached credentials from this machine").addHelpText("after", `
+Purely local — already-issued access tokens stay valid until they expire
+(about an hour). Running it while signed out is fine.`).action(async () => {
+		const cache = buildPca().getTokenCache();
+		for (const account of await cache.getAllAccounts()) await cache.removeAccount(account);
+		rmSync(TOKEN_CACHE_PATH, { force: true });
+		console.log("Signed out.");
+	});
+}
+//#endregion
 //#region ../lib/tutors/assemble.ts
 const COMPILE_OPTIONS = {
 	strict: true,
@@ -447,8 +798,8 @@ function resolveRelativeUrl(ref, baseUrl) {
 /**
 * Resolve a fragment-file reference to an absolute URL. An absolute http(s) ref is used
 * as-is; anything else is treated as relative to the tutor URL — standard URL resolution
-* drops the tutor's filename and appends the relative path (so `general-fragments.yaml`
-* next to `.../activities/tutors/linked-list-tutor.yaml` becomes `.../activities/tutors/general-fragments.yaml`,
+* drops the tutor's filename and appends the relative path (so `my-fragments.yaml`
+* next to `.../tutors/my-tutor.yaml` becomes `.../tutors/my-fragments.yaml`,
 * and `./` / `../` segments work too). Throws if a relative ref is unparseable; the schema
 * already guarantees the only inputs here are http(s) URLs or relative paths.
 */
@@ -1096,11 +1447,51 @@ function formatOutcome(outcome, source) {
 	}
 }
 //#endregion
+//#region src/commands/whoami.ts
+function registerWhoami(program) {
+	program.command("whoami").description("Show who is signed in by calling the Novedu server's /api/me").option("--server <url>", "Novedu server base URL (defaults to the NOVEDU_SERVER env var, then production)").action(async (options) => {
+		let token;
+		try {
+			token = await getAccessToken();
+		} catch (error) {
+			if (error instanceof NotSignedInError) {
+				console.error(error.message);
+				process.exitCode = 1;
+				return;
+			}
+			throw error;
+		}
+		const server = resolveServerUrl(options.server);
+		let response;
+		try {
+			response = await fetch(new URL("/api/me", server), { headers: { authorization: `Bearer ${token}` } });
+		} catch (error) {
+			console.error(`Could not reach ${server}: ${error instanceof Error ? error.message : error}`);
+			process.exitCode = 1;
+			return;
+		}
+		if (!response.ok) {
+			console.error(`${server} rejected the request: HTTP ${response.status}`);
+			process.exitCode = 1;
+			return;
+		}
+		const me = await response.json();
+		console.log(`Signed in as ${me.name ?? "(no name)"}`);
+		console.log(`User id: ${me.userId}`);
+		console.log(`Teacher: ${me.isTeacher ? "yes" : "no"}`);
+	});
+}
+//#endregion
 //#region src/main.ts
 const { version } = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8"));
 const program = new Command();
 program.name("novedu-cli").description("Command-line companion for the Novedu chat app").version(version);
 registerValidate(program);
+registerLogin(program);
+registerLogout(program);
+registerWhoami(program);
+registerCodes(program);
+registerFiles(program);
 program.parseAsync().catch((err) => {
 	console.error(err instanceof Error ? err.message : err);
 	process.exitCode = 1;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@novedu/cli",
-  "version": "0.6.0",
-  "description": "Command-line companion for the Novedu chat app. Validates tutor, fragment, quiz, writing and coding YAML definitions (more commands to follow).",
+  "version": "0.8.0",
+  "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": {
     "type": "git",
@@ -15,7 +15,7 @@
     "dist"
   ],
   "engines": {
-    "node": ">=18"
+    "node": ">=20"
   },
   "publishConfig": {
     "access": "public"
@@ -25,6 +25,7 @@
     "prepublishOnly": "npm run build"
   },
   "dependencies": {
+    "@azure/msal-node": "^5.3.1",
     "commander": "^15.0.0",
     "handlebars": "^4.7.9",
     "yaml": "^2.9.0",