@novedu/cli 0.3.0 → 0.4.0

package/README.md

@@ -1,7 +1,10 @@
 # @novedu/cli
 
 Command-line companion for the Novedu chat app (installed command: `novedu-cli`).
-Today it validates **tutor YAML** definitions; more commands will follow.
+Today it validates **tutor YAML** definitions and **fragment libraries**; more
+commands will follow. Validating a tutor also fully validates every fragment
+library it references; pass `--kind fragment` to validate a fragment library on
+its own.
 
 It reuses the app's exact validation pipeline (`lib/tutors`), so a tutor that
 passes here is the same tutor the app would accept — no separate, drifting rules.
@@ -15,10 +18,15 @@ npx @novedu/cli validate ./tutors/simple-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/tutors/simple-tutor.yaml
 
+# Validate a fragment library on its own
+npx @novedu/cli validate ./tutors/simple-fragments.yaml --kind fragment
+
 # Machine-readable output (the raw validation result)
 npx @novedu/cli validate ./tutors/simple-tutor.yaml --json
 ```
 
+`--kind` defaults to `tutor`; it is caller-declared, not auto-detected.
+
 Exit code is `0` when the tutor is valid and `1` when it has errors, so it works
 as a pre-commit / CI gate.
 

package/dist/main.js

@@ -1,4 +1,5 @@
 #!/usr/bin/env node
+import { readFileSync } from "node:fs";
 import { Command } from "commander";
 import { resolve } from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
@@ -44,7 +45,7 @@ function warning(code, message, extra = {}) {
 * Flattens a treeified Zod error into `path: message` lines so a generic
 * "Document does not match the expected structure" becomes actionable — e.g.
 * `Unrecognized key: "nae"` and `name: Invalid input: expected string`.
-* Framework-agnostic: shared by the web UI (`ErrorList`), the share-tutor
+* Framework-agnostic: shared by the web UI (`ErrorList`), the tutor-code
 * action, and the CLI formatter, so a schema error reads the same everywhere.
 */
 function formatZodIssues(zodIssues) {
@@ -428,6 +429,18 @@ function checkFragmentFileValue(parsed, url) {
 	};
 }
 //#endregion
+//#region ../lib/relative-url.ts
+/**
+* Resolve a reference to an absolute URL. An absolute http(s) ref is used as-is;
+* anything else is treated as relative to `baseUrl` — standard URL resolution drops
+* the base's filename and appends the relative path (so `./` / `../` segments work too).
+* Throws if a relative ref is unparseable.
+*/
+function resolveRelativeUrl(ref, baseUrl) {
+	if (/^https?:\/\//i.test(ref)) return ref;
+	return new URL(ref, baseUrl).href;
+}
+//#endregion
 //#region ../lib/tutors/load.ts
 /**
 * Resolve a fragment-file reference to an absolute URL. An absolute http(s) ref is used
@@ -438,8 +451,7 @@ function checkFragmentFileValue(parsed, url) {
 * already guarantees the only inputs here are http(s) URLs or relative paths.
 */
 function resolveFragmentUrl(ref, tutorUrl) {
-	if (/^https?:\/\//i.test(ref)) return ref;
-	return new URL(ref, tutorUrl).href;
+	return resolveRelativeUrl(ref, tutorUrl);
 }
 async function fetchText(url, fetchImpl) {
 	try {
@@ -466,8 +478,9 @@ 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 and the
-* standalone fragment checker so both gate schemes identically.
+* 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.
 */
 async function loadYaml(url, fetchImpl, opts = {}) {
 	const allowedSchemes = opts.allowedSchemes ?? DEFAULT_ALLOWED_SCHEMES;
@@ -615,6 +628,150 @@ async function loadAndCheckFragmentFile(url, fetchImpl, opts = {}) {
 	return checkFragmentFileValue(yaml.value, url);
 }
 //#endregion
+//#region ../lib/quiz-schema.ts
+/** An optional content image attached to a question (carries no secret). */
+const ImageRefSchema = z.strictObject({
+	hosted: z.boolean().optional(),
+	src: z.string().min(1),
+	alt: z.string().optional(),
+	credit: z.string().optional()
+});
+/**
+* One question. `id` keys the per-question stats (must be unique — see
+* `lib/quiz-validate.ts`); `question` is the Markdown shown to the student;
+* `evaluation` is the server-only grading prompt.
+*/
+const QuizQuestionSchema = z.strictObject({
+	id: z.string().min(1),
+	title: z.string().optional(),
+	question: z.string().min(1),
+	evaluation: z.string().min(1),
+	image: ImageRefSchema.optional()
+});
+const QuizYamlSchema = z.strictObject({
+	id: z.string().min(1),
+	name: z.string().optional(),
+	title: z.string().optional(),
+	description: z.string().optional(),
+	anonymous: z.boolean().optional(),
+	shuffle: z.boolean().optional(),
+	llm: z.strictObject({ model: z.string().min(1) }),
+	discussion: z.strictObject({ instructions: z.string().min(1) }).optional(),
+	questions: z.array(QuizQuestionSchema).min(1)
+});
+//#endregion
+//#region ../lib/quiz-validate.ts
+/** Quizzes default to anonymous — answers are recorded for stats but not attributed. */
+const DEFAULT_ANONYMOUS$1 = true;
+/** Question ids declared on more than one question (the per-question stats key). */
+function findDuplicateQuestionIds(quiz) {
+	const errors = [];
+	const seen = /* @__PURE__ */ new Set();
+	for (const question of quiz.questions) {
+		if (seen.has(question.id)) {
+			errors.push(error("DUPLICATE_QUIZ_QUESTION_ID", `Question id "${question.id}" is declared more than once`, { questionId: question.id }));
+			continue;
+		}
+		seen.add(question.id);
+	}
+	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.
+*/
+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;
+	const errors = findDuplicateQuestionIds(quiz);
+	if (errors.length > 0) return {
+		ok: false,
+		errors,
+		warnings: []
+	};
+	return {
+		ok: true,
+		quizId: quiz.id,
+		model: quiz.llm.model,
+		questionCount: quiz.questions.length,
+		anonymous: quiz.anonymous ?? DEFAULT_ANONYMOUS$1,
+		title: quiz.title ?? null,
+		warnings: []
+	};
+}
+/**
+* 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.
+*/
+async function loadAndCheckQuiz(url, fetchImpl, opts = {}) {
+	const yaml = await loadYaml(url, fetchImpl, opts);
+	if (!yaml.ok) return {
+		ok: false,
+		errors: [yaml.error],
+		warnings: []
+	};
+	return checkQuizValue(yaml.value, url);
+}
+//#endregion
+//#region ../lib/writing-schema.ts
+const WritingYamlSchema = z.strictObject({
+	id: z.string().min(1),
+	name: z.string().optional(),
+	title: z.string().optional(),
+	description: z.string().optional(),
+	anonymous: z.boolean().optional(),
+	llm: z.strictObject({ model: z.string().min(1) }),
+	instructions: z.string().min(1),
+	placeholder: z.string().optional()
+});
+//#endregion
+//#region ../lib/writing-validate.ts
+/** 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.
+*/
+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;
+	return {
+		ok: true,
+		writingId: writing.id,
+		model: writing.llm.model,
+		anonymous: writing.anonymous ?? DEFAULT_ANONYMOUS,
+		title: writing.title ?? null,
+		warnings: []
+	};
+}
+/**
+* Validate a writing FILE: scheme-gate + fetch + parse (shared `loadYaml`), then the
+* pure `checkWritingValue`. The web app passes the default http(s)-only schemes; the
+* CLI adds `file:` so a local writing YAML on disk validates too.
+*/
+async function loadAndCheckWriting(url, fetchImpl, opts = {}) {
+	const yaml = await loadYaml(url, fetchImpl, opts);
+	if (!yaml.ok) return {
+		ok: false,
+		errors: [yaml.error],
+		warnings: []
+	};
+	return checkWritingValue(yaml.value, url);
+}
+//#endregion
 //#region src/file-fetcher.ts
 const cliFetcher = async (url) => {
 	if (url.startsWith("file:")) try {
@@ -646,6 +803,7 @@ function context(item) {
 	const parts = [];
 	if (item.fileAlias) parts.push(`file=${item.fileAlias}`);
 	if (item.fragmentId) parts.push(`fragment=${item.fragmentId}`);
+	if ("questionId" in item && item.questionId) parts.push(`question=${item.questionId}`);
 	if (item.variable) parts.push(`variable=${item.variable}`);
 	if ("url" in item && item.url) parts.push(`url=${item.url}`);
 	if ("expectedType" in item && item.expectedType) parts.push(`expected=${item.expectedType}`);
@@ -719,8 +877,58 @@ function formatFragmentResult(result, source) {
 	}
 	return lines.join("\n");
 }
+/**
+* Shared tail for the quiz/writing renderers: on failure, the error list (with any
+* flattened Zod issues); plus any warnings on either branch.
+*/
+function renderFailureAndWarnings(result, label, source) {
+	const lines = [red(`✘ Invalid ${label}`) + dim(` — ${source}`), ""];
+	lines.push(red(`${result.errors.length} error(s):`));
+	lines.push(...renderErrors(result.errors));
+	if (result.warnings.length) {
+		lines.push("");
+		lines.push(yellow(`${result.warnings.length} warning(s):`));
+		lines.push(...renderWarnings(result.warnings));
+	}
+	return lines.join("\n");
+}
+/** Renderer for a quiz check (`--kind quiz`). */
+function formatQuizResult(result, source) {
+	if (!result.ok) return renderFailureAndWarnings(result, "quiz", source);
+	const lines = [green(`✔ Valid quiz`) + dim(` — ${source}`)];
+	lines.push(`  id: ${result.quizId}`);
+	lines.push(`  model: ${result.model}`);
+	lines.push(`  questions: ${result.questionCount}   anonymous: ${result.anonymous}`);
+	if (result.warnings.length) {
+		lines.push("");
+		lines.push(yellow(`${result.warnings.length} warning(s):`));
+		lines.push(...renderWarnings(result.warnings));
+	}
+	return lines.join("\n");
+}
+/** Renderer for a writing-activity check (`--kind writing`). */
+function formatWritingResult(result, source) {
+	if (!result.ok) return renderFailureAndWarnings(result, "writing activity", source);
+	const lines = [green(`✔ Valid writing activity`) + dim(` — ${source}`)];
+	lines.push(`  id: ${result.writingId}`);
+	lines.push(`  model: ${result.model}`);
+	lines.push(`  anonymous: ${result.anonymous}`);
+	if (result.warnings.length) {
+		lines.push("");
+		lines.push(yellow(`${result.warnings.length} warning(s):`));
+		lines.push(...renderWarnings(result.warnings));
+	}
+	return lines.join("\n");
+}
 //#endregion
 //#region src/commands/validate.ts
+/** Every kind the `--kind` flag accepts (used for the option help + guard). */
+const VALIDATE_KINDS = [
+	"tutor",
+	"fragment",
+	"quiz",
+	"writing"
+];
 /**
 * Turn the CLI argument into a URL the tutor core understands: an http(s) URL is
 * used as-is; anything else is treated as a filesystem path and converted to an
@@ -744,20 +952,30 @@ function runValidate(pathOrUrl, kind) {
 		"https:",
 		"file:"
 	];
-	if (kind === "fragment") return loadAndCheckFragmentFile(url, cliFetcher, { allowedSchemes }).then((result) => ({
-		kind,
-		result
-	}));
-	return loadAndBuildTutorPrompt(url, cliFetcher, {
-		allowedSchemes,
-		validateLibraries: true
-	}).then((result) => ({
-		kind,
-		result
-	}));
+	switch (kind) {
+		case "fragment": return loadAndCheckFragmentFile(url, cliFetcher, { allowedSchemes }).then((result) => ({
+			kind,
+			result
+		}));
+		case "quiz": return loadAndCheckQuiz(url, cliFetcher, { allowedSchemes }).then((result) => ({
+			kind,
+			result
+		}));
+		case "writing": return loadAndCheckWriting(url, cliFetcher, { allowedSchemes }).then((result) => ({
+			kind,
+			result
+		}));
+		default: return loadAndBuildTutorPrompt(url, cliFetcher, {
+			allowedSchemes,
+			validateLibraries: true
+		}).then((result) => ({
+			kind,
+			result
+		}));
+	}
 }
 function registerValidate(program) {
-	program.command("validate").description("Validate a tutor YAML (default) or a fragment library by local path or public http(s) URL").argument("<pathOrUrl>", "path to a tutor or fragment YAML file, or a public http(s) URL").option("--kind <kind>", "what the file is: 'tutor' (default) or 'fragment'", "tutor").option("--json", "print the raw validation result as JSON").addHelpText("after", `
+	program.command("validate").description("Validate a tutor (default), fragment library, quiz or writing YAML by local path or public http(s) URL").argument("<pathOrUrl>", "path to a tutor, fragment, quiz or writing YAML file, or a public http(s) URL").option("--kind <kind>", `what the file is: ${VALIDATE_KINDS.map((k) => `'${k}'`).join(", ")} ('tutor' is the default)`, "tutor").option("--json", "print the raw validation result as JSON").addHelpText("after", `
 Examples:
   # Validate a tutor (also strict-renders every fragment in every referenced library)
   $ novedu-cli validate ./tutors/my-tutor.yaml
@@ -765,23 +983,37 @@ Examples:
   # Validate a fragment library on its own
   $ novedu-cli validate ./tutors/my-fragments.yaml --kind fragment
 
+  # Validate a quiz or a writing activity
+  $ novedu-cli validate ./quizzes/my-quiz.yaml --kind quiz
+  $ novedu-cli validate ./writings/my-writing.yaml --kind writing
+
   # Machine-readable output for CI
   $ novedu-cli validate https://example.com/tutor.yaml --json`).action(async (pathOrUrl, options) => {
-		if (options.kind !== void 0 && options.kind !== "tutor" && options.kind !== "fragment") {
-			console.error(`Invalid --kind "${options.kind}": expected "tutor" or "fragment".`);
+		if (options.kind !== void 0 && !VALIDATE_KINDS.includes(options.kind)) {
+			console.error(`Invalid --kind "${options.kind}": expected ${VALIDATE_KINDS.map((k) => `"${k}"`).join(", ")}.`);
 			process.exitCode = 1;
 			return;
 		}
-		const outcome = await runValidate(pathOrUrl, options.kind === "fragment" ? "fragment" : "tutor");
+		const outcome = await runValidate(pathOrUrl, options.kind ?? "tutor");
 		if (options.json) console.log(JSON.stringify(outcome.result, null, 2));
-		else console.log(outcome.kind === "fragment" ? formatFragmentResult(outcome.result, pathOrUrl) : formatResult(outcome.result, pathOrUrl));
+		else console.log(formatOutcome(outcome, pathOrUrl));
 		process.exitCode = outcome.result.ok ? 0 : 1;
 	});
 }
+/** Pick the formatter for the outcome's kind (each result type has its own renderer). */
+function formatOutcome(outcome, source) {
+	switch (outcome.kind) {
+		case "fragment": return formatFragmentResult(outcome.result, source);
+		case "quiz": return formatQuizResult(outcome.result, source);
+		case "writing": return formatWritingResult(outcome.result, source);
+		default: return formatResult(outcome.result, source);
+	}
+}
 //#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("0.2.0");
+program.name("novedu-cli").description("Command-line companion for the Novedu chat app").version(version);
 registerValidate(program);
 program.parseAsync().catch((err) => {
 	console.error(err instanceof Error ? err.message : err);

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@novedu/cli",
-  "version": "0.3.0",
-  "description": "Command-line companion for the Novedu chat app. Validates tutor YAML definitions and fragment libraries (more commands to follow).",
+  "version": "0.4.0",
+  "description": "Command-line companion for the Novedu chat app. Validates tutor, fragment, quiz and writing YAML definitions (more commands to follow).",
   "type": "module",
   "repository": {
     "type": "git",