@novedu/cli 0.7.0 → 0.9.0

package/dist/main.js

@@ -6,11 +6,11 @@ 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";
@@ -185,6 +185,143 @@ 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", `
@@ -221,25 +358,34 @@ Purely local — already-issued access tokens stay valid until they expire
 	});
 }
 //#endregion
-//#region ../lib/tutors/assemble.ts
+//#region ../lib/prompt-fragments/assemble.ts
 const COMPILE_OPTIONS = {
 	strict: true,
 	noEscape: true
 };
 /**
-* Render each fragment in priority order and append the tutor-specific
-* instructions last (they carry no priority, so "after everything" is the only
-* deterministic position). May throw if a template references a missing variable.
+* Render each fragment in priority order and, when provided, append the caller's
+* trailing instructions last (they carry no priority, so "after everything" is the
+* only deterministic position — the exact role `tutor_instructions` plays for a
+* tutor, and the activity frame / `instructions` play for quiz / writing / coding).
+* May throw if a template references a missing variable.
+*
+* `trailingInstructions` is optional so a consumer can assemble a fragment-only
+* PREAMBLE (quiz / writing / coding) and concatenate its own frame afterwards. An
+* empty plan with no trailing text renders to the empty string (so an activity that
+* declares no fragments gets no stray whitespace); every non-empty result ends in a
+* single trailing newline, byte-identical to the historic tutor output.
 */
-function assembleSystemPrompt(plan, tutor) {
+function assembleSystemPrompt(plan, trailingInstructions) {
 	const parts = plan.map((fragment) => {
 		return Handlebars.compile(fragment.content, COMPILE_OPTIONS)(fragment.variables).trimEnd();
 	});
-	parts.push(tutor.prompt.tutor_instructions.trimEnd());
+	if (trailingInstructions !== void 0) parts.push(trailingInstructions.trimEnd());
+	if (parts.length === 0) return "";
 	return `${parts.join("\n\n")}\n`;
 }
 //#endregion
-//#region ../lib/tutors/errors.ts
+//#region ../lib/prompt-fragments/errors.ts
 /** Small helper to build an error object tersely at call sites. */
 function error(code, message, extra = {}) {
 	return {
@@ -276,7 +422,7 @@ function formatZodIssues(zodIssues) {
 	return out;
 }
 //#endregion
-//#region ../lib/tutors/consistency.ts
+//#region ../lib/prompt-fragments/consistency.ts
 /** Compare a supplied value against its declared property type. Returns null when it matches. */
 function typeMismatch(prop, value) {
 	const actual = Array.isArray(value) ? "array" : typeof value;
@@ -295,11 +441,11 @@ function typeMismatch(prop, value) {
 		};
 	}
 }
-function checkConsistency(tutor, fragmentFilesByAlias) {
+function checkConsistency(block, fragmentFilesByAlias) {
 	const errors = [];
 	const warnings = [];
 	const aliasCounts = /* @__PURE__ */ new Map();
-	for (const ref of tutor.prompt.fragment_files) aliasCounts.set(ref.id, (aliasCounts.get(ref.id) ?? 0) + 1);
+	for (const ref of block.fragment_files) aliasCounts.set(ref.id, (aliasCounts.get(ref.id) ?? 0) + 1);
 	for (const [alias, count] of aliasCounts) if (count > 1) errors.push(error("DUPLICATE_FRAGMENT_FILE_ALIAS", `Fragment-file alias "${alias}" is declared ${count} times`, { fileAlias: alias }));
 	const fragmentIndex = /* @__PURE__ */ new Map();
 	for (const [alias, file] of fragmentFilesByAlias) {
@@ -318,7 +464,7 @@ function checkConsistency(tutor, fragmentFilesByAlias) {
 	}
 	const resolved = [];
 	const seenRefs = /* @__PURE__ */ new Set();
-	for (const ref of tutor.prompt.fragments) {
+	for (const ref of block.fragments) {
 		const refKey = `${ref.file}::${ref.id}`;
 		if (seenRefs.has(refKey)) warnings.push(warning("DUPLICATE_FRAGMENT_REFERENCE", `Fragment "${ref.id}" from "${ref.file}" is referenced more than once`, {
 			fileAlias: ref.file,
@@ -410,7 +556,7 @@ function checkConsistency(tutor, fragmentFilesByAlias) {
 	};
 }
 //#endregion
-//#region ../lib/tutors/fetcher.ts
+//#region ../lib/prompt-fragments/fetcher.ts
 const DEFAULT_TIMEOUT_MS = 1e4;
 /** Production fetcher: global `fetch` with an abort-based timeout so a slow host can't hang the request. */
 const defaultFetcher = async (url) => {
@@ -426,7 +572,7 @@ const defaultFetcher = async (url) => {
 	}
 };
 //#endregion
-//#region ../lib/tutors/parse.ts
+//#region ../lib/prompt-fragments/parse.ts
 /** Parse a YAML document, mapping syntax errors to a structured `YAML_PARSE_ERROR`. */
 function parseYaml(text, url) {
 	try {
@@ -456,12 +602,11 @@ function validate(value, schema, code, url) {
 		})
 	};
 }
-const providerSchema = z.enum(["SCCH", "Azure Foundry"]).default("SCCH");
 //#endregion
-//#region ../lib/tutors/schemas.ts
+//#region ../lib/prompt-fragments/schemas.ts
 /**
 * A fragment-file reference: either an absolute http(s) URL or a relative path that
-* `load.ts` resolves against the tutor YAML's own URL. We reject any *other* absolute
+* `load.ts` resolves against the activity YAML's own URL. We reject any *other* absolute
 * scheme (`ftp:`, `mailto:`, …) so a typo can't smuggle in a non-http(s) target — the
 * refine reads as "if it carries a URI scheme at all, that scheme must be http(s)".
 * Strings without a scheme (relative paths) pass through and are resolved at load time.
@@ -470,7 +615,7 @@ const FragmentUrlRef = z.string().min(1).refine((u) => !/^[a-z][a-z0-9+.-]*:/i.t
 /**
 * A declared property is a string, a boolean, or an array of strings. Each may carry an
 * optional `default`, typed to match its `type` (a string default on a boolean property
-* is a schema error). When the tutor omits the variable, the default is used; supplying
+* is a schema error). When the activity omits the variable, the default is used; supplying
 * a value overrides it. See `consistency.ts` for where defaults are injected.
 */
 const PropertySchema = z.discriminatedUnion("type", [
@@ -526,35 +671,8 @@ const FragmentRefSchema = z.strictObject({
 	bind: z.record(z.string(), z.string()).optional(),
 	required: z.boolean().optional()
 });
-/**
-* An example question offered to students on the welcome screen: the `title` is
-* the clickable label, the `question` is the full text placed into the chat
-* input on click. Tutors may define any number; the UI samples at most 5.
-*/
-const ExampleQuestionSchema = z.strictObject({
-	title: z.string().min(1),
-	question: z.string().min(1)
-});
-const TutorSchema = z.strictObject({
-	id: z.string(),
-	name: z.string(),
-	title: z.string().optional(),
-	description: z.string(),
-	exampleQuestions: z.array(ExampleQuestionSchema).optional(),
-	anonymous: z.boolean().optional(),
-	llm: z.strictObject({
-		model: z.string(),
-		provider: providerSchema,
-		imageInput: z.boolean().optional()
-	}),
-	prompt: z.strictObject({
-		fragment_files: z.array(FragmentFileRefSchema).default([]),
-		fragments: z.array(FragmentRefSchema).default([]),
-		tutor_instructions: z.string()
-	})
-});
 //#endregion
-//#region ../lib/tutors/fragment.ts
+//#region ../lib/prompt-fragments/fragment.ts
 /**
 * A placeholder value for a declared input, shaped to its type so the template
 * actually exercises it: a string renders, a boolean drives `{{#if}}`, an array
@@ -657,17 +775,17 @@ function resolveRelativeUrl(ref, baseUrl) {
 	return new URL(ref, baseUrl).href;
 }
 //#endregion
-//#region ../lib/tutors/load.ts
+//#region ../lib/prompt-fragments/load.ts
 /**
 * 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 `my-fragments.yaml`
+* as-is; anything else is treated as relative to the activity URL — standard URL resolution
+* drops the activity'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.
 */
-function resolveFragmentUrl(ref, tutorUrl) {
-	return resolveRelativeUrl(ref, tutorUrl);
+function resolveFragmentUrl(ref, baseUrl) {
+	return resolveRelativeUrl(ref, baseUrl);
 }
 async function fetchText(url, fetchImpl) {
 	try {
@@ -692,23 +810,33 @@ async function fetchText(url, fetchImpl) {
 }
 const DEFAULT_ALLOWED_SCHEMES = ["http:", "https:"];
 /**
-* The shared front of every load: enforce the URL scheme allow-list (SSRF guard),
-* fetch the document, and parse it as YAML — returning the parsed-but-not-yet-schema-
-* validated value or the first structured error. Reused by the tutor builder, the
-* standalone fragment checker, and the quiz/writing validators so they all gate
-* schemes identically.
+* The SSRF scheme gate shared by the top-level activity load (`loadYaml`) and every
+* fragment-file fetch (`assembleFragmentPrompt`): a URL is allowed only if its scheme
+* is in `allowedSchemes` (default http(s); the CLI adds `file:` for on-disk validation).
+* Returns the structured error to surface, or `null` when the scheme is allowed.
 */
-async function loadYaml(url, fetchImpl, opts = {}) {
-	const allowedSchemes = opts.allowedSchemes ?? DEFAULT_ALLOWED_SCHEMES;
+function schemeGate(url, allowedSchemes) {
 	let scheme;
 	try {
 		scheme = new URL(url).protocol;
 	} catch {
 		scheme = "";
 	}
-	if (!allowedSchemes.includes(scheme)) return {
+	if (allowedSchemes.includes(scheme)) return null;
+	return error("INVALID_URL", `Provide a valid ${allowedSchemes.map((s) => s.replace(/:$/, "")).join("/")} URL`, { url });
+}
+/**
+* The shared front of every load: enforce the URL scheme allow-list (SSRF guard),
+* fetch the document, and parse it as YAML — returning the parsed-but-not-yet-schema-
+* validated value or the first structured error. Reused by the activity builders, the
+* standalone fragment checker, and the quiz/writing/coding validators so they all gate
+* schemes identically.
+*/
+async function loadYaml(url, fetchImpl, opts = {}) {
+	const schemeError = schemeGate(url, opts.allowedSchemes ?? DEFAULT_ALLOWED_SCHEMES);
+	if (schemeError) return {
 		ok: false,
-		error: error("INVALID_URL", `Provide a valid ${allowedSchemes.map((s) => s.replace(/:$/, "")).join("/")} URL`, { url })
+		error: schemeError
 	};
 	const fetched = await fetchText(url, fetchImpl);
 	if (!fetched.ok) return {
@@ -725,25 +853,30 @@ async function loadYaml(url, fetchImpl, opts = {}) {
 		value: parsed.value
 	};
 }
-async function loadAndBuildTutorPrompt(url, fetchImpl, opts = {}) {
+/**
+* Resolve a document-level fragment block to a finished prompt string: fetch every
+* declared fragment file in parallel (relative refs resolved against `baseUrl`),
+* schema-validate each, (optionally) run the thorough whole-library check, check
+* consistency, and assemble the priority-ordered plan followed by the optional
+* `trailingInstructions`.
+*
+* The single seam every activity kind shares — the sole owner of the fetch → validate
+* → consistency → assemble pipeline. Consumers concatenate their own frame only when
+* they pass no `trailingInstructions` (a fragment-only preamble); tutors pass their
+* `tutor_instructions` and get a complete prompt.
+*/
+async function assembleFragmentPrompt(block, baseUrl, fetchImpl, opts = {}, trailingInstructions) {
 	const warnings = [];
-	const tutorYaml = await loadYaml(url, fetchImpl, opts);
-	if (!tutorYaml.ok) return {
-		ok: false,
-		errors: [tutorYaml.error],
-		warnings
-	};
-	const tutorValid = validate(tutorYaml.value, TutorSchema, "TUTOR_SCHEMA_ERROR", url);
-	if (!tutorValid.ok) return {
-		ok: false,
-		errors: [tutorValid.error],
+	const allowedSchemes = opts.allowedSchemes ?? DEFAULT_ALLOWED_SCHEMES;
+	if (block.fragment_files.length === 0 && block.fragments.length === 0) return {
+		ok: true,
+		prompt: assembleSystemPrompt([], trailingInstructions),
 		warnings
 	};
-	const tutor = tutorValid.data;
-	const settled = await Promise.all(tutor.prompt.fragment_files.map(async (ref) => {
+	const settled = await Promise.all(block.fragment_files.map(async (ref) => {
 		let fragmentUrl;
 		try {
-			fragmentUrl = resolveFragmentUrl(ref.url, url);
+			fragmentUrl = resolveFragmentUrl(ref.url, baseUrl);
 		} catch {
 			return {
 				alias: ref.id,
@@ -753,6 +886,14 @@ async function loadAndBuildTutorPrompt(url, fetchImpl, opts = {}) {
 				})
 			};
 		}
+		const schemeError = schemeGate(fragmentUrl, allowedSchemes);
+		if (schemeError) return {
+			alias: ref.id,
+			error: {
+				...schemeError,
+				fileAlias: ref.id
+			}
+		};
 		const fetched = await fetchText(fragmentUrl, fetchImpl);
 		if (!fetched.ok) return {
 			alias: ref.id,
@@ -799,7 +940,7 @@ async function loadAndBuildTutorPrompt(url, fetchImpl, opts = {}) {
 		libraryErrors.push(...checked.errors);
 		warnings.push(...checked.warnings);
 	}
-	const consistency = checkConsistency(tutor, fragmentFilesByAlias);
+	const consistency = checkConsistency(block, fragmentFilesByAlias);
 	warnings.push(...consistency.warnings);
 	const preAssemblyErrors = [...libraryErrors, ...consistency.errors];
 	if (preAssemblyErrors.length > 0) return {
@@ -810,14 +951,7 @@ async function loadAndBuildTutorPrompt(url, fetchImpl, opts = {}) {
 	try {
 		return {
 			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,
-			description: tutor.description,
-			exampleQuestions: tutor.exampleQuestions ?? [],
+			prompt: assembleSystemPrompt(consistency.plan, trailingInstructions),
 			warnings
 		};
 	} catch (e) {
@@ -831,9 +965,9 @@ async function loadAndBuildTutorPrompt(url, fetchImpl, opts = {}) {
 /**
 * Validate a fragment FILE on its own (the `--kind fragment` / "Fragment library"
 * path): scheme-gate + fetch + parse, then the pure `checkFragmentFileValue`. A
-* fragment library is self-contained, so — unlike a tutor — there are no further
+* fragment library is self-contained, so — unlike an activity — there are no further
 * files to fetch. The caller already knows it asked for a fragment, so this returns
-* a `FragmentCheckResult` directly (no tutor `BuildResult`, no kind discriminator).
+* a `FragmentCheckResult` directly (no activity `BuildResult`, no kind discriminator).
 */
 async function loadAndCheckFragmentFile(url, fetchImpl, opts = {}) {
 	const yaml = await loadYaml(url, fetchImpl, opts);
@@ -844,6 +978,7 @@ async function loadAndCheckFragmentFile(url, fetchImpl, opts = {}) {
 	};
 	return checkFragmentFileValue(yaml.value, url);
 }
+const providerSchema = z.enum(["SCCH", "Azure Foundry"]).default("SCCH");
 //#endregion
 //#region ../lib/coding-schema.ts
 const CodingYamlSchema = z.strictObject({
@@ -854,23 +989,18 @@ const CodingYamlSchema = z.strictObject({
 		model: z.string().min(1),
 		provider: providerSchema
 	}),
+	fragment_files: z.array(FragmentFileRefSchema).default([]),
+	fragments: z.array(FragmentRefSchema).default([]),
 	instructions: z.string().min(1)
 });
 //#endregion
 //#region ../lib/coding-validate.ts
 /**
-* Validate an already-parsed coding value against its schema, then extract metadata.
-* Pure (the parsed value is passed in); `loadAndCheckCoding` wraps it with fetch +
-* YAML parse.
+* Extract metadata from an already-schema-validated coding value. Split from
+* `checkCodingValue` so `loadAndCheckCoding` can reuse the single `validate` it already
+* ran (no second parse of the same document against the same schema).
 */
-function checkCodingValue(parsed, url) {
-	const valid = validate(parsed, CodingYamlSchema, "CODING_SCHEMA_ERROR", url);
-	if (!valid.ok) return {
-		ok: false,
-		errors: [valid.error],
-		warnings: []
-	};
-	const coding = valid.data;
+function checkCodingParsed(coding) {
 	return {
 		ok: true,
 		codingId: coding.id,
@@ -892,7 +1022,31 @@ async function loadAndCheckCoding(url, fetchImpl, opts = {}) {
 		errors: [yaml.error],
 		warnings: []
 	};
-	return checkCodingValue(yaml.value, url);
+	const valid = validate(yaml.value, CodingYamlSchema, "CODING_SCHEMA_ERROR", url);
+	if (!valid.ok) return {
+		ok: false,
+		errors: [valid.error],
+		warnings: []
+	};
+	const checked = checkCodingParsed(valid.data);
+	if (!checked.ok) return checked;
+	const assembled = await assembleFragmentPrompt({
+		fragment_files: valid.data.fragment_files,
+		fragments: valid.data.fragments
+	}, url, fetchImpl, {
+		allowedSchemes: opts.allowedSchemes,
+		validateLibraries: opts.validateLibraries ?? true
+	});
+	const warnings = [...checked.warnings, ...assembled.warnings];
+	if (!assembled.ok) return {
+		ok: false,
+		errors: assembled.errors,
+		warnings
+	};
+	return {
+		...checked,
+		warnings
+	};
 }
 //#endregion
 //#region ../lib/quiz-schema.ts
@@ -913,7 +1067,8 @@ const QuizQuestionSchema = z.strictObject({
 	title: z.string().optional(),
 	question: z.string().min(1),
 	evaluation: z.string().min(1),
-	image: ImageRefSchema.optional()
+	image: ImageRefSchema.optional(),
+	imageInput: z.boolean().optional()
 });
 const QuizYamlSchema = z.strictObject({
 	id: z.string().min(1),
@@ -924,9 +1079,12 @@ const QuizYamlSchema = z.strictObject({
 	shuffle: z.boolean().optional(),
 	llm: z.strictObject({
 		model: z.string().min(1),
-		provider: providerSchema
+		provider: providerSchema,
+		imageInput: z.boolean().optional()
 	}),
 	discussion: z.strictObject({ instructions: z.string().min(1) }).optional(),
+	fragment_files: z.array(FragmentFileRefSchema).default([]),
+	fragments: z.array(FragmentRefSchema).default([]),
 	questions: z.array(QuizQuestionSchema).min(1)
 });
 //#endregion
@@ -947,18 +1105,11 @@ function findDuplicateQuestionIds(quiz) {
 	return errors;
 }
 /**
-* Validate an already-parsed quiz value: schema → unique question ids → metadata.
-* Pure (the parsed value is passed in); `loadAndCheckQuiz` wraps it with fetch +
-* YAML parse.
+* Check an already-schema-validated quiz: unique question ids → metadata. Split from
+* `checkQuizValue` so `loadAndCheckQuiz` can reuse the single `validate` it already ran
+* (no second parse of the same document against the same schema).
 */
-function checkQuizValue(parsed, url) {
-	const valid = validate(parsed, QuizYamlSchema, "QUIZ_SCHEMA_ERROR", url);
-	if (!valid.ok) return {
-		ok: false,
-		errors: [valid.error],
-		warnings: []
-	};
-	const quiz = valid.data;
+function checkQuizParsed(quiz) {
 	const errors = findDuplicateQuestionIds(quiz);
 	if (errors.length > 0) return {
 		ok: false,
@@ -977,9 +1128,11 @@ function checkQuizValue(parsed, url) {
 	};
 }
 /**
-* Validate a quiz FILE: scheme-gate + fetch + parse (shared `loadYaml`), then the
-* pure `checkQuizValue`. The web app passes the default http(s)-only schemes; the
-* CLI adds `file:` so a local quiz YAML on disk validates too.
+* Validate a quiz FILE: scheme-gate + fetch + parse (shared `loadYaml`), the pure
+* `checkQuizValue`, then the document-level fragment block's authoring gate — fetch
+* every referenced library, run the THOROUGH whole-library check, consistency, and an
+* assembly dry-run (the strict-Handlebars backstop). The web app passes the default
+* http(s)-only schemes; the CLI adds `file:` so a local quiz YAML on disk validates too.
 */
 async function loadAndCheckQuiz(url, fetchImpl, opts = {}) {
 	const yaml = await loadYaml(url, fetchImpl, opts);
@@ -988,7 +1141,97 @@ async function loadAndCheckQuiz(url, fetchImpl, opts = {}) {
 		errors: [yaml.error],
 		warnings: []
 	};
-	return checkQuizValue(yaml.value, url);
+	const valid = validate(yaml.value, QuizYamlSchema, "QUIZ_SCHEMA_ERROR", url);
+	if (!valid.ok) return {
+		ok: false,
+		errors: [valid.error],
+		warnings: []
+	};
+	const checked = checkQuizParsed(valid.data);
+	if (!checked.ok) return checked;
+	const assembled = await assembleFragmentPrompt({
+		fragment_files: valid.data.fragment_files,
+		fragments: valid.data.fragments
+	}, url, fetchImpl, {
+		allowedSchemes: opts.allowedSchemes,
+		validateLibraries: opts.validateLibraries ?? true
+	});
+	const warnings = [...checked.warnings, ...assembled.warnings];
+	if (!assembled.ok) return {
+		ok: false,
+		errors: assembled.errors,
+		warnings
+	};
+	return {
+		...checked,
+		warnings
+	};
+}
+//#endregion
+//#region ../lib/tutors/schemas.ts
+/**
+* An example question offered to students on the welcome screen: the `title` is
+* the clickable label, the `question` is the full text placed into the chat
+* input on click. Tutors may define any number; the UI samples at most 5.
+*/
+const ExampleQuestionSchema = z.strictObject({
+	title: z.string().min(1),
+	question: z.string().min(1)
+});
+const TutorSchema = z.strictObject({
+	id: z.string(),
+	name: z.string(),
+	title: z.string().optional(),
+	description: z.string(),
+	exampleQuestions: z.array(ExampleQuestionSchema).optional(),
+	anonymous: z.boolean().optional(),
+	llm: z.strictObject({
+		model: z.string(),
+		provider: providerSchema,
+		imageInput: z.boolean().optional()
+	}),
+	prompt: z.strictObject({
+		fragment_files: z.array(FragmentFileRefSchema).default([]),
+		fragments: z.array(FragmentRefSchema).default([]),
+		tutor_instructions: z.string()
+	})
+});
+//#endregion
+//#region ../lib/tutors/load.ts
+async function loadAndBuildTutorPrompt(url, fetchImpl, opts = {}) {
+	const warnings = [];
+	const tutorYaml = await loadYaml(url, fetchImpl, opts);
+	if (!tutorYaml.ok) return {
+		ok: false,
+		errors: [tutorYaml.error],
+		warnings
+	};
+	const tutorValid = validate(tutorYaml.value, TutorSchema, "TUTOR_SCHEMA_ERROR", url);
+	if (!tutorValid.ok) return {
+		ok: false,
+		errors: [tutorValid.error],
+		warnings
+	};
+	const tutor = tutorValid.data;
+	const assembled = await assembleFragmentPrompt(tutor.prompt, url, fetchImpl, opts, tutor.prompt.tutor_instructions);
+	warnings.push(...assembled.warnings);
+	if (!assembled.ok) return {
+		ok: false,
+		errors: assembled.errors,
+		warnings
+	};
+	return {
+		ok: true,
+		prompt: assembled.prompt,
+		model: tutor.llm.model,
+		provider: tutor.llm.provider,
+		imageInput: tutor.llm.imageInput ?? true,
+		anonymous: tutor.anonymous ?? true,
+		title: tutor.title,
+		description: tutor.description,
+		exampleQuestions: tutor.exampleQuestions ?? [],
+		warnings
+	};
 }
 //#endregion
 //#region ../lib/writing-schema.ts
@@ -1002,6 +1245,8 @@ const WritingYamlSchema = z.strictObject({
 		model: z.string().min(1),
 		provider: providerSchema
 	}),
+	fragment_files: z.array(FragmentFileRefSchema).default([]),
+	fragments: z.array(FragmentRefSchema).default([]),
 	instructions: z.string().min(1),
 	placeholder: z.string().optional()
 });
@@ -1010,18 +1255,11 @@ const WritingYamlSchema = z.strictObject({
 /** Writing DIVERGES from tutor/quiz: it defaults to attributed (`anonymous: false`). */
 const DEFAULT_ANONYMOUS = false;
 /**
-* Validate an already-parsed writing value against its schema, then extract metadata.
-* Pure (the parsed value is passed in); `loadAndCheckWriting` wraps it with fetch +
-* YAML parse.
+* Extract metadata from an already-schema-validated writing value. Split from
+* `checkWritingValue` so `loadAndCheckWriting` can reuse the single `validate` it already
+* ran (no second parse of the same document against the same schema).
 */
-function checkWritingValue(parsed, url) {
-	const valid = validate(parsed, WritingYamlSchema, "WRITING_SCHEMA_ERROR", url);
-	if (!valid.ok) return {
-		ok: false,
-		errors: [valid.error],
-		warnings: []
-	};
-	const writing = valid.data;
+function checkWritingParsed(writing) {
 	return {
 		ok: true,
 		writingId: writing.id,
@@ -1044,7 +1282,31 @@ async function loadAndCheckWriting(url, fetchImpl, opts = {}) {
 		errors: [yaml.error],
 		warnings: []
 	};
-	return checkWritingValue(yaml.value, url);
+	const valid = validate(yaml.value, WritingYamlSchema, "WRITING_SCHEMA_ERROR", url);
+	if (!valid.ok) return {
+		ok: false,
+		errors: [valid.error],
+		warnings: []
+	};
+	const checked = checkWritingParsed(valid.data);
+	if (!checked.ok) return checked;
+	const assembled = await assembleFragmentPrompt({
+		fragment_files: valid.data.fragment_files,
+		fragments: valid.data.fragments
+	}, url, fetchImpl, {
+		allowedSchemes: opts.allowedSchemes,
+		validateLibraries: opts.validateLibraries ?? true
+	});
+	const warnings = [...checked.warnings, ...assembled.warnings];
+	if (!assembled.ok) return {
+		ok: false,
+		errors: assembled.errors,
+		warnings
+	};
+	return {
+		...checked,
+		warnings
+	};
 }
 //#endregion
 //#region src/file-fetcher.ts
@@ -1310,12 +1572,6 @@ 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) => {
@@ -1359,6 +1615,8 @@ 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.7.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.9.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",
@@ -25,13 +25,13 @@
     "prepublishOnly": "npm run build"
   },
   "dependencies": {
-    "@azure/msal-node": "^5.3.1",
+    "@azure/msal-node": "^5.4.0",
     "commander": "^15.0.0",
     "handlebars": "^4.7.9",
     "yaml": "^2.9.0",
     "zod": "^4.4.3"
   },
   "devDependencies": {
-    "tsdown": "^0.22.3"
+    "tsdown": "^0.22.4"
   }
 }