@novedu/cli 0.5.1 → 0.7.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,226 @@
 #!/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 { 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/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,
@@ -242,6 +456,7 @@ function validate(value, schema, code, url) {
 		})
 	};
 }
+const providerSchema = z.enum(["SCCH", "Azure Foundry"]).default("SCCH");
 //#endregion
 //#region ../lib/tutors/schemas.ts
 /**
@@ -329,6 +544,7 @@ const TutorSchema = z.strictObject({
 	anonymous: z.boolean().optional(),
 	llm: z.strictObject({
 		model: z.string(),
+		provider: providerSchema,
 		imageInput: z.boolean().optional()
 	}),
 	prompt: z.strictObject({
@@ -445,8 +661,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.
 */
@@ -596,6 +812,7 @@ async function loadAndBuildTutorPrompt(url, fetchImpl, opts = {}) {
 			ok: true,
 			prompt: assembleSystemPrompt(consistency.plan, tutor),
 			model: tutor.llm.model,
+			provider: tutor.llm.provider,
 			imageInput: tutor.llm.imageInput ?? true,
 			anonymous: tutor.anonymous ?? true,
 			title: tutor.title,
@@ -633,7 +850,10 @@ const CodingYamlSchema = z.strictObject({
 	id: z.string().min(1),
 	name: z.string().optional(),
 	title: z.string().optional(),
-	llm: z.strictObject({ model: z.string().min(1) }),
+	llm: z.strictObject({
+		model: z.string().min(1),
+		provider: providerSchema
+	}),
 	instructions: z.string().min(1)
 });
 //#endregion
@@ -655,6 +875,7 @@ function checkCodingValue(parsed, url) {
 		ok: true,
 		codingId: coding.id,
 		model: coding.llm.model,
+		provider: coding.llm.provider,
 		title: coding.title ?? null,
 		warnings: []
 	};
@@ -701,7 +922,10 @@ const QuizYamlSchema = z.strictObject({
 	description: z.string().optional(),
 	anonymous: z.boolean().optional(),
 	shuffle: z.boolean().optional(),
-	llm: z.strictObject({ model: z.string().min(1) }),
+	llm: z.strictObject({
+		model: z.string().min(1),
+		provider: providerSchema
+	}),
 	discussion: z.strictObject({ instructions: z.string().min(1) }).optional(),
 	questions: z.array(QuizQuestionSchema).min(1)
 });
@@ -745,6 +969,7 @@ function checkQuizValue(parsed, url) {
 		ok: true,
 		quizId: quiz.id,
 		model: quiz.llm.model,
+		provider: quiz.llm.provider,
 		questionCount: quiz.questions.length,
 		anonymous: quiz.anonymous ?? DEFAULT_ANONYMOUS$1,
 		title: quiz.title ?? null,
@@ -773,7 +998,10 @@ const WritingYamlSchema = z.strictObject({
 	title: z.string().optional(),
 	description: z.string().optional(),
 	anonymous: z.boolean().optional(),
-	llm: z.strictObject({ model: z.string().min(1) }),
+	llm: z.strictObject({
+		model: z.string().min(1),
+		provider: providerSchema
+	}),
 	instructions: z.string().min(1),
 	placeholder: z.string().optional()
 });
@@ -798,6 +1026,7 @@ function checkWritingValue(parsed, url) {
 		ok: true,
 		writingId: writing.id,
 		model: writing.llm.model,
+		provider: writing.llm.provider,
 		anonymous: writing.anonymous ?? DEFAULT_ANONYMOUS,
 		title: writing.title ?? null,
 		warnings: []
@@ -1081,11 +1310,55 @@ function formatOutcome(outcome, source) {
 	}
 }
 //#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/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);
 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.5.1",
+  "version": "0.7.0",
   "description": "Command-line companion for the Novedu chat app. Validates tutor, fragment, quiz, writing and coding YAML definitions (more commands to follow).",
   "type": "module",
   "repository": {
@@ -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",