@novedu/cli 0.1.0

package/README.md

@@ -0,0 +1,36 @@
+# @novedu/cli
+
+Command-line companion for the Novedu chat app (installed command: `novedu-cli`).
+Today it validates **tutor YAML** definitions; more commands will follow.
+
+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.
+
+## Usage
+
+```bash
+# Validate a local file (relative fragment_files resolve from the same folder)
+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
+
+# Machine-readable output (the raw validation result)
+npx @novedu/cli validate ./tutors/simple-tutor.yaml --json
+```
+
+Exit code is `0` when the tutor is valid and `1` when it has errors, so it works
+as a pre-commit / CI gate.
+
+## Development
+
+The CLI lives in the app repo as an npm workspace.
+
+```bash
+npm run cli -- validate ./tutors/simple-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)
+```
+
+The fast in-process unit test (`cli/src/commands/validate.unit.test.ts`) runs in
+CI; the integration tests hit the network and are local-only.

package/dist/main.js

@@ -0,0 +1,568 @@
+#!/usr/bin/env node
+import { Command } from "commander";
+import { resolve } from "node:path";
+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 ../lib/tutors/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.
+*/
+function assembleSystemPrompt(plan, tutor) {
+	const parts = plan.map((fragment) => {
+		return Handlebars.compile(fragment.content, COMPILE_OPTIONS)(fragment.variables).trimEnd();
+	});
+	parts.push(tutor.prompt.tutor_instructions.trimEnd());
+	return `${parts.join("\n\n")}\n`;
+}
+//#endregion
+//#region ../lib/tutors/errors.ts
+/** Small helper to build an error object tersely at call sites. */
+function error(code, message, extra = {}) {
+	return {
+		code,
+		message,
+		...extra
+	};
+}
+function warning(code, message, extra = {}) {
+	return {
+		code,
+		message,
+		...extra
+	};
+}
+//#endregion
+//#region ../lib/tutors/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;
+	switch (prop.type) {
+		case "string": return typeof value === "string" ? null : {
+			expected: "string",
+			actual
+		};
+		case "boolean": return typeof value === "boolean" ? null : {
+			expected: "boolean",
+			actual
+		};
+		case "array": return Array.isArray(value) && value.every((v) => typeof v === "string") ? null : {
+			expected: "array<string>",
+			actual
+		};
+	}
+}
+function checkConsistency(tutor, 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 [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) {
+		const byId = /* @__PURE__ */ new Map();
+		for (const frag of file.fragments) {
+			if (byId.has(frag.id)) {
+				errors.push(error("DUPLICATE_FRAGMENT_ID_IN_FILE", `Fragment "${frag.id}" is declared more than once in file "${alias}"`, {
+					fileAlias: alias,
+					fragmentId: frag.id
+				}));
+				continue;
+			}
+			byId.set(frag.id, frag);
+		}
+		fragmentIndex.set(alias, byId);
+	}
+	const resolved = [];
+	const seenRefs = /* @__PURE__ */ new Set();
+	for (const ref of tutor.prompt.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,
+			fragmentId: ref.id
+		}));
+		seenRefs.add(refKey);
+		const byId = fragmentIndex.get(ref.file);
+		if (!byId) {
+			errors.push(error("UNKNOWN_FRAGMENT_FILE_ALIAS", `Fragment reference uses unknown file alias "${ref.file}"`, {
+				fileAlias: ref.file,
+				fragmentId: ref.id
+			}));
+			continue;
+		}
+		const fragment = byId.get(ref.id);
+		if (!fragment) {
+			errors.push(error("FRAGMENT_NOT_FOUND", `Fragment "${ref.id}" not found in file "${ref.file}"`, {
+				fileAlias: ref.file,
+				fragmentId: ref.id
+			}));
+			continue;
+		}
+		const variables = ref.variables ?? {};
+		const schema = fragment.input_schema;
+		const merged = { ...variables };
+		if (schema) {
+			for (const name of schema.required) if (!(name in variables)) errors.push(error("MISSING_REQUIRED_VARIABLE", `Fragment "${ref.id}" requires variable "${name}", which is not supplied`, {
+				fileAlias: ref.file,
+				fragmentId: ref.id,
+				variable: name
+			}));
+			for (const [name, value] of Object.entries(variables)) {
+				const prop = schema.properties[name];
+				if (!prop) {
+					warnings.push(warning("UNDECLARED_VARIABLE", `Variable "${name}" supplied to "${ref.id}" is not declared in its input schema`, {
+						fileAlias: ref.file,
+						fragmentId: ref.id,
+						variable: name
+					}));
+					continue;
+				}
+				const mismatch = typeMismatch(prop, value);
+				if (mismatch) errors.push(error("VARIABLE_TYPE_MISMATCH", `Variable "${name}" of "${ref.id}" should be ${mismatch.expected} but got ${mismatch.actual}`, {
+					fileAlias: ref.file,
+					fragmentId: ref.id,
+					variable: name,
+					expectedType: mismatch.expected,
+					actualType: mismatch.actual
+				}));
+			}
+			const requiredSet = new Set(schema.required);
+			for (const [name, prop] of Object.entries(schema.properties)) {
+				if (prop.default === void 0) continue;
+				if (requiredSet.has(name)) {
+					warnings.push(warning("REQUIRED_PROPERTY_HAS_DEFAULT", `Variable "${name}" of "${ref.id}" is required, so its default is never used`, {
+						fileAlias: ref.file,
+						fragmentId: ref.id,
+						variable: name
+					}));
+					continue;
+				}
+				if (!(name in merged)) merged[name] = prop.default;
+			}
+		} else for (const name of Object.keys(variables)) warnings.push(warning("UNDECLARED_VARIABLE", `Variable "${name}" supplied to "${ref.id}", which declares no input schema`, {
+			fileAlias: ref.file,
+			fragmentId: ref.id,
+			variable: name
+		}));
+		resolved.push({
+			fileAlias: ref.file,
+			fragmentId: ref.id,
+			priority: fragment.priority,
+			content: fragment.content,
+			variables: merged
+		});
+	}
+	const plan = [...resolved].sort((a, b) => a.priority - b.priority);
+	const priorityOwners = /* @__PURE__ */ new Map();
+	for (const r of resolved) {
+		const owners = priorityOwners.get(r.priority) ?? [];
+		owners.push(r.fragmentId);
+		priorityOwners.set(r.priority, owners);
+	}
+	for (const [priority, owners] of priorityOwners) if (owners.length > 1) errors.push(error("DUPLICATE_PRIORITY", `Priority ${priority} is shared by fragments: ${owners.join(", ")} — ordering is ambiguous`));
+	return {
+		errors,
+		warnings,
+		plan
+	};
+}
+//#endregion
+//#region ../lib/tutors/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) => {
+	const controller = new AbortController();
+	const timeout = setTimeout(() => controller.abort(), DEFAULT_TIMEOUT_MS);
+	try {
+		return await fetch(url, {
+			signal: controller.signal,
+			redirect: "follow"
+		});
+	} finally {
+		clearTimeout(timeout);
+	}
+};
+//#endregion
+//#region ../lib/tutors/parse.ts
+/** Parse a YAML document, mapping syntax errors to a structured `YAML_PARSE_ERROR`. */
+function parseYaml(text, url) {
+	try {
+		return {
+			ok: true,
+			value: parse(text)
+		};
+	} catch (e) {
+		return {
+			ok: false,
+			error: error("YAML_PARSE_ERROR", `Invalid YAML: ${e instanceof Error ? e.message : String(e)}`, { url })
+		};
+	}
+}
+/** Validate an already-parsed value against a Zod schema, attaching treeified issues on failure. */
+function validate(value, schema, code, url) {
+	const result = schema.safeParse(value);
+	if (result.success) return {
+		ok: true,
+		data: result.data
+	};
+	return {
+		ok: false,
+		error: error(code, "Document does not match the expected structure", {
+			url,
+			zodIssues: z.treeifyError(result.error)
+		})
+	};
+}
+//#endregion
+//#region ../lib/tutors/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
+* 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.
+*/
+const FragmentUrlRef = z.string().min(1).refine((u) => !/^[a-z][a-z0-9+.-]*:/i.test(u) || /^https?:\/\//i.test(u), { message: "Must be an http(s) URL or a relative path" });
+/**
+* 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
+* a value overrides it. See `consistency.ts` for where defaults are injected.
+*/
+const PropertySchema = z.discriminatedUnion("type", [
+	z.strictObject({
+		type: z.literal("string"),
+		default: z.string().optional()
+	}),
+	z.strictObject({
+		type: z.literal("boolean"),
+		default: z.boolean().optional()
+	}),
+	z.strictObject({
+		type: z.literal("array"),
+		items: z.strictObject({ type: z.literal("string") }),
+		default: z.array(z.string()).optional()
+	})
+]);
+const InputSchema = z.strictObject({
+	type: z.literal("object"),
+	required: z.array(z.string()).default([]),
+	properties: z.record(z.string(), PropertySchema).default({})
+});
+const ClassificationSchema = z.strictObject({
+	type: z.string(),
+	override_allowed: z.boolean().optional()
+});
+const FragmentSchema = z.strictObject({
+	id: z.string(),
+	version: z.number(),
+	priority: z.number(),
+	input_schema: InputSchema.optional(),
+	classification: ClassificationSchema.optional(),
+	content: z.string()
+});
+const FragmentFileSchema = z.strictObject({
+	id: z.string(),
+	fragments: z.array(FragmentSchema).min(1)
+});
+/** A supplied variable value mirrors what `input_schema` can declare. */
+const VariableValueSchema = z.union([
+	z.string(),
+	z.boolean(),
+	z.array(z.string())
+]);
+const FragmentFileRefSchema = z.strictObject({
+	id: z.string(),
+	url: FragmentUrlRef
+});
+const FragmentRefSchema = z.strictObject({
+	file: z.string(),
+	id: z.string(),
+	variables: z.record(z.string(), VariableValueSchema).optional(),
+	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(),
+		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
+/**
+* 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 `.../tutors/linked-list-tutor.yaml` becomes `.../tutors/general-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) {
+	if (/^https?:\/\//i.test(ref)) return ref;
+	return new URL(ref, tutorUrl).href;
+}
+async function fetchText(url, fetchImpl) {
+	try {
+		const res = await fetchImpl(url);
+		if (!res.ok) return {
+			ok: false,
+			error: error("FETCH_FAILED", `Failed to fetch ${url} (HTTP ${res.status})`, {
+				url,
+				status: res.status
+			})
+		};
+		return {
+			ok: true,
+			text: await res.text()
+		};
+	} catch (e) {
+		return {
+			ok: false,
+			error: error("FETCH_FAILED", `Failed to fetch ${url}: ${e instanceof Error ? e.message : String(e)}`, { url })
+		};
+	}
+}
+const DEFAULT_ALLOWED_SCHEMES = ["http:", "https:"];
+async function loadAndBuildTutorPrompt(url, fetchImpl, opts = {}) {
+	const warnings = [];
+	const allowedSchemes = opts.allowedSchemes ?? DEFAULT_ALLOWED_SCHEMES;
+	let scheme;
+	try {
+		scheme = new URL(url).protocol;
+	} catch {
+		scheme = "";
+	}
+	if (!allowedSchemes.includes(scheme)) return {
+		ok: false,
+		errors: [error("INVALID_URL", `Provide a valid ${allowedSchemes.map((s) => s.replace(/:$/, "")).join("/")} URL`, { url })],
+		warnings
+	};
+	const tutorFetch = await fetchText(url, fetchImpl);
+	if (!tutorFetch.ok) return {
+		ok: false,
+		errors: [tutorFetch.error],
+		warnings
+	};
+	const tutorYaml = parseYaml(tutorFetch.text, url);
+	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 settled = await Promise.all(tutor.prompt.fragment_files.map(async (ref) => {
+		let fragmentUrl;
+		try {
+			fragmentUrl = resolveFragmentUrl(ref.url, url);
+		} catch {
+			return {
+				alias: ref.id,
+				error: error("INVALID_URL", `Invalid fragment URL: ${ref.url}`, {
+					url: ref.url,
+					fileAlias: ref.id
+				})
+			};
+		}
+		const fetched = await fetchText(fragmentUrl, fetchImpl);
+		if (!fetched.ok) return {
+			alias: ref.id,
+			error: fetched.error
+		};
+		const parsed = parseYaml(fetched.text, fragmentUrl);
+		if (!parsed.ok) return {
+			alias: ref.id,
+			error: parsed.error
+		};
+		const valid = validate(parsed.value, FragmentFileSchema, "FRAGMENT_FILE_SCHEMA_ERROR", fragmentUrl);
+		if (!valid.ok) return {
+			alias: ref.id,
+			error: {
+				...valid.error,
+				fileAlias: ref.id
+			}
+		};
+		return {
+			alias: ref.id,
+			file: valid.data
+		};
+	}));
+	const fragmentFilesByAlias = /* @__PURE__ */ new Map();
+	const fileErrors = [];
+	for (const result of settled) if ("error" in result) fileErrors.push(result.error);
+	else fragmentFilesByAlias.set(result.alias, result.file);
+	if (fileErrors.length > 0) return {
+		ok: false,
+		errors: fileErrors,
+		warnings
+	};
+	const consistency = checkConsistency(tutor, fragmentFilesByAlias);
+	warnings.push(...consistency.warnings);
+	if (consistency.errors.length > 0) return {
+		ok: false,
+		errors: consistency.errors,
+		warnings
+	};
+	try {
+		return {
+			ok: true,
+			prompt: assembleSystemPrompt(consistency.plan, tutor),
+			model: tutor.llm.model,
+			imageInput: tutor.llm.imageInput ?? true,
+			anonymous: tutor.anonymous ?? true,
+			title: tutor.title,
+			description: tutor.description,
+			exampleQuestions: tutor.exampleQuestions ?? [],
+			warnings
+		};
+	} catch (e) {
+		return {
+			ok: false,
+			errors: [error("ASSEMBLY_ERROR", `Failed to render system prompt: ${e instanceof Error ? e.message : String(e)}`)],
+			warnings
+		};
+	}
+}
+//#endregion
+//#region src/file-fetcher.ts
+const cliFetcher = async (url) => {
+	if (url.startsWith("file:")) try {
+		const text = await readFile(fileURLToPath(url), "utf8");
+		return {
+			ok: true,
+			status: 200,
+			text: async () => text
+		};
+	} catch {
+		return {
+			ok: false,
+			status: 404,
+			text: async () => ""
+		};
+	}
+	return defaultFetcher(url);
+};
+//#endregion
+//#region src/format.ts
+const useColor = process.stdout.isTTY && !process.env.NO_COLOR;
+const paint = (code, s) => useColor ? `\x1b[${code}m${s}\x1b[0m` : s;
+const green = (s) => paint("32", s);
+const red = (s) => paint("31", s);
+const yellow = (s) => paint("33", s);
+const dim = (s) => paint("2", s);
+/** Append the context fields an error/warning carries, when present. */
+function context(item) {
+	const parts = [];
+	if (item.fileAlias) parts.push(`file=${item.fileAlias}`);
+	if (item.fragmentId) parts.push(`fragment=${item.fragmentId}`);
+	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}`);
+	if ("actualType" in item && item.actualType) parts.push(`actual=${item.actualType}`);
+	return parts.length ? dim(` (${parts.join(", ")})`) : "";
+}
+function renderWarnings(warnings) {
+	return warnings.map((w) => `  ${yellow("⚠")} ${yellow(w.code)} ${w.message}${context(w)}`);
+}
+function formatResult(result, source) {
+	const lines = [];
+	if (result.ok) {
+		lines.push(green(`✔ Valid tutor`) + dim(` — ${source}`));
+		lines.push(`  model: ${result.model}`);
+		lines.push(`  system prompt: ${result.prompt.length} chars`);
+		lines.push(`  imageInput: ${result.imageInput}   anonymous: ${result.anonymous}` + (result.exampleQuestions.length ? `   exampleQuestions: ${result.exampleQuestions.length}` : ""));
+		if (result.warnings.length) {
+			lines.push("");
+			lines.push(yellow(`${result.warnings.length} warning(s):`));
+			lines.push(...renderWarnings(result.warnings));
+		}
+		return lines.join("\n");
+	}
+	lines.push(red(`✘ Invalid tutor`) + dim(` — ${source}`));
+	lines.push("");
+	lines.push(red(`${result.errors.length} error(s):`));
+	for (const e of result.errors) lines.push(`  ${red("✗")} ${red(e.code)} ${e.message}${context(e)}`);
+	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
+/**
+* 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
+* absolute `file://` URL.
+*/
+function toUrl(pathOrUrl) {
+	if (/^https?:\/\//i.test(pathOrUrl)) return pathOrUrl;
+	return pathToFileURL(resolve(pathOrUrl)).href;
+}
+/**
+* The validate command's pure core: run the existing tutor pipeline over a local
+* file or public URL. Kept separate from the commander wiring so it can be unit
+* tested in-process. `file:` is allowed in addition to http(s) so local YAML can
+* be validated (the web app deliberately stays http(s)-only).
+*/
+function runValidate(pathOrUrl) {
+	return loadAndBuildTutorPrompt(toUrl(pathOrUrl), cliFetcher, { allowedSchemes: [
+		"http:",
+		"https:",
+		"file:"
+	] });
+}
+function registerValidate(program) {
+	program.command("validate").description("Validate a tutor YAML by local path or public http(s) URL").argument("<pathOrUrl>", "path to a tutor YAML file, or a public http(s) URL").option("--json", "print the raw validation result as JSON").action(async (pathOrUrl, options) => {
+		const result = await runValidate(pathOrUrl);
+		if (options.json) console.log(JSON.stringify(result, null, 2));
+		else console.log(formatResult(result, pathOrUrl));
+		process.exitCode = result.ok ? 0 : 1;
+	});
+}
+//#endregion
+//#region src/main.ts
+const program = new Command();
+program.name("novedu-cli").description("Command-line companion for the Novedu chat app").version("0.1.0");
+registerValidate(program);
+program.parseAsync().catch((err) => {
+	console.error(err instanceof Error ? err.message : err);
+	process.exitCode = 1;
+});
+//#endregion
+export {};

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "@novedu/cli",
+  "version": "0.1.0",
+  "description": "Command-line companion for the Novedu chat app. Validates tutor YAML definitions (more commands to follow).",
+  "type": "module",
+  "bin": {
+    "novedu-cli": "dist/main.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsdown"
+  },
+  "dependencies": {
+    "commander": "^15.0.0",
+    "handlebars": "^4.7.9",
+    "yaml": "^2.9.0",
+    "zod": "^4.4.3"
+  },
+  "devDependencies": {
+    "tsdown": "^0.22.2"
+  }
+}