@novedu/cli 0.1.2 → 0.3.0

package/dist/main.js

@@ -40,6 +40,26 @@ function warning(code, message, extra = {}) {
 		...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
+* action, and the CLI formatter, so a schema error reads the same everywhere.
+*/
+function formatZodIssues(zodIssues) {
+	const out = [];
+	const walk = (node, path) => {
+		if (!node || typeof node !== "object") return;
+		if (Array.isArray(node.errors)) for (const message of node.errors) out.push(path.length ? `${path.join(".")}: ${message}` : message);
+		if (node.properties) for (const [key, child] of Object.entries(node.properties)) walk(child, [...path, key]);
+		if (Array.isArray(node.items)) node.items.forEach((child, index) => {
+			walk(child, [...path, String(index)]);
+		});
+	};
+	walk(zodIssues, []);
+	return out;
+}
 //#endregion
 //#region ../lib/tutors/consistency.ts
 /** Compare a supplied value against its declared property type. Returns null when it matches. */
@@ -317,6 +337,97 @@ const TutorSchema = z.strictObject({
 	})
 });
 //#endregion
+//#region ../lib/tutors/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
+* makes `{{#each}}` run its body (so references inside the loop are checked too). We
+* deliberately ignore the fragment's real `default`s — we only need *some* value of
+* the right shape, so that strict rendering throws solely on variables the fragment
+* never declares.
+*/
+function placeholder(prop) {
+	switch (prop.type) {
+		case "string": return "x";
+		case "boolean": return true;
+		case "array": return ["x"];
+	}
+}
+/** Synthetic render context = every declared property name → a typed placeholder. */
+function placeholderContext(fragment) {
+	const ctx = {};
+	for (const [name, prop] of Object.entries(fragment.input_schema?.properties ?? {})) ctx[name] = placeholder(prop);
+	return ctx;
+}
+/**
+* Strict-render each fragment's `content` against a context built from its own
+* `input_schema`. A throw — a Handlebars syntax error, or `strict` mode hitting a
+* variable not in the context (one the fragment never declares) — becomes a
+* `FRAGMENT_TEMPLATE_ERROR`. Uses the SAME compile options as real prompt assembly
+* (`assemble.ts`), so passing here ⟺ rendering inside a tutor. `fileAlias`/`url` are
+* stamped for attribution when this runs as part of a tutor's whole-library check.
+*/
+function checkFragmentTemplates(file, opts = {}) {
+	const errors = [];
+	for (const fragment of file.fragments) try {
+		Handlebars.compile(fragment.content, COMPILE_OPTIONS)(placeholderContext(fragment));
+	} catch (e) {
+		const message = e instanceof Error ? e.message : String(e);
+		errors.push(error("FRAGMENT_TEMPLATE_ERROR", `Fragment "${fragment.id}" failed to render: ${message}`, {
+			fragmentId: fragment.id,
+			fileAlias: opts.fileAlias,
+			url: opts.url
+		}));
+	}
+	return {
+		errors,
+		warnings: []
+	};
+}
+/**
+* Fragment ids declared more than once within a single file. The standalone
+* validator runs this directly; the tutor path gets the same check from
+* `checkConsistency` (so the whole-library pass must NOT repeat it).
+*/
+function findDuplicateFragmentIds(file) {
+	const errors = [];
+	const seen = /* @__PURE__ */ new Set();
+	for (const fragment of file.fragments) {
+		if (seen.has(fragment.id)) {
+			errors.push(error("DUPLICATE_FRAGMENT_ID_IN_FILE", `Fragment "${fragment.id}" is declared more than once`, { fragmentId: fragment.id }));
+			continue;
+		}
+		seen.add(fragment.id);
+	}
+	return errors;
+}
+/**
+* Validate a fragment FILE on its own: schema → unique ids → every template renders.
+* Pure (the parsed value is passed in); `loadAndCheckFragmentFile` in `load.ts` wraps
+* it with fetch + YAML parse. On success, reports the file id and its fragment ids.
+*/
+function checkFragmentFileValue(parsed, url) {
+	const valid = validate(parsed, FragmentFileSchema, "FRAGMENT_FILE_SCHEMA_ERROR", url);
+	if (!valid.ok) return {
+		ok: false,
+		errors: [valid.error],
+		warnings: []
+	};
+	const file = valid.data;
+	const errors = [...findDuplicateFragmentIds(file), ...checkFragmentTemplates(file, { url }).errors];
+	if (errors.length > 0) return {
+		ok: false,
+		errors,
+		warnings: []
+	};
+	return {
+		ok: true,
+		fragmentFileId: file.id,
+		fragmentIds: file.fragments.map((f) => f.id),
+		warnings: []
+	};
+}
+//#endregion
 //#region ../lib/tutors/load.ts
 /**
 * Resolve a fragment-file reference to an absolute URL. An absolute http(s) ref is used
@@ -352,8 +463,13 @@ async function fetchText(url, fetchImpl) {
 	}
 }
 const DEFAULT_ALLOWED_SCHEMES = ["http:", "https:"];
-async function loadAndBuildTutorPrompt(url, fetchImpl, opts = {}) {
-	const warnings = [];
+/**
+* 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.
+*/
+async function loadYaml(url, fetchImpl, opts = {}) {
 	const allowedSchemes = opts.allowedSchemes ?? DEFAULT_ALLOWED_SCHEMES;
 	let scheme;
 	try {
@@ -363,16 +479,26 @@ async function loadAndBuildTutorPrompt(url, fetchImpl, opts = {}) {
 	}
 	if (!allowedSchemes.includes(scheme)) return {
 		ok: false,
-		errors: [error("INVALID_URL", `Provide a valid ${allowedSchemes.map((s) => s.replace(/:$/, "")).join("/")} URL`, { url })],
-		warnings
+		error: error("INVALID_URL", `Provide a valid ${allowedSchemes.map((s) => s.replace(/:$/, "")).join("/")} URL`, { url })
 	};
-	const tutorFetch = await fetchText(url, fetchImpl);
-	if (!tutorFetch.ok) return {
+	const fetched = await fetchText(url, fetchImpl);
+	if (!fetched.ok) return {
 		ok: false,
-		errors: [tutorFetch.error],
-		warnings
+		error: fetched.error
+	};
+	const parsed = parseYaml(fetched.text, url);
+	if (!parsed.ok) return {
+		ok: false,
+		error: parsed.error
 	};
-	const tutorYaml = parseYaml(tutorFetch.text, url);
+	return {
+		ok: true,
+		value: parsed.value
+	};
+}
+async function loadAndBuildTutorPrompt(url, fetchImpl, opts = {}) {
+	const warnings = [];
+	const tutorYaml = await loadYaml(url, fetchImpl, opts);
 	if (!tutorYaml.ok) return {
 		ok: false,
 		errors: [tutorYaml.error],
@@ -418,23 +544,38 @@ async function loadAndBuildTutorPrompt(url, fetchImpl, opts = {}) {
 		};
 		return {
 			alias: ref.id,
-			file: valid.data
+			file: valid.data,
+			url: fragmentUrl
 		};
 	}));
 	const fragmentFilesByAlias = /* @__PURE__ */ new Map();
+	const fragmentUrlByAlias = /* @__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);
+	else {
+		fragmentFilesByAlias.set(result.alias, result.file);
+		fragmentUrlByAlias.set(result.alias, result.url);
+	}
 	if (fileErrors.length > 0) return {
 		ok: false,
 		errors: fileErrors,
 		warnings
 	};
+	const libraryErrors = [];
+	if (opts.validateLibraries) for (const [alias, file] of fragmentFilesByAlias) {
+		const checked = checkFragmentTemplates(file, {
+			fileAlias: alias,
+			url: fragmentUrlByAlias.get(alias)
+		});
+		libraryErrors.push(...checked.errors);
+		warnings.push(...checked.warnings);
+	}
 	const consistency = checkConsistency(tutor, fragmentFilesByAlias);
 	warnings.push(...consistency.warnings);
-	if (consistency.errors.length > 0) return {
+	const preAssemblyErrors = [...libraryErrors, ...consistency.errors];
+	if (preAssemblyErrors.length > 0) return {
 		ok: false,
-		errors: consistency.errors,
+		errors: preAssemblyErrors,
 		warnings
 	};
 	try {
@@ -457,6 +598,22 @@ 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
+* files to fetch. The caller already knows it asked for a fragment, so this returns
+* a `FragmentCheckResult` directly (no tutor `BuildResult`, no kind discriminator).
+*/
+async function loadAndCheckFragmentFile(url, fetchImpl, opts = {}) {
+	const yaml = await loadYaml(url, fetchImpl, opts);
+	if (!yaml.ok) return {
+		ok: false,
+		errors: [yaml.error],
+		warnings: []
+	};
+	return checkFragmentFileValue(yaml.value, url);
+}
 //#endregion
 //#region src/file-fetcher.ts
 const cliFetcher = async (url) => {
@@ -498,6 +655,20 @@ function context(item) {
 function renderWarnings(warnings) {
 	return warnings.map((w) => `  ${yellow("⚠")} ${yellow(w.code)} ${w.message}${context(w)}`);
 }
+/**
+* Render each error as a line, with any flattened Zod schema-issue detail
+* indented beneath it — so a generic "Document does not match the expected
+* structure" is followed by the actual field paths (e.g. `Unrecognized key:
+* "nae"`), matching what the web UI shows.
+*/
+function renderErrors(errors) {
+	const lines = [];
+	for (const e of errors) {
+		lines.push(`  ${red("✗")} ${red(e.code)} ${e.message}${context(e)}`);
+		if (e.zodIssues) for (const issue of formatZodIssues(e.zodIssues)) lines.push(`      ${dim(issue)}`);
+	}
+	return lines;
+}
 function formatResult(result, source) {
 	const lines = [];
 	if (result.ok) {
@@ -515,7 +686,32 @@ function formatResult(result, source) {
 	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)}`);
+	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");
+}
+/** Same renderer, for a standalone fragment-FILE check (`--kind fragment`). */
+function formatFragmentResult(result, source) {
+	const lines = [];
+	if (result.ok) {
+		lines.push(green(`✔ Valid fragment file`) + dim(` — ${source}`));
+		lines.push(`  id: ${result.fragmentFileId}`);
+		lines.push(`  fragments: ${result.fragmentIds.length}` + (result.fragmentIds.length ? ` (${result.fragmentIds.join(", ")})` : ""));
+		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 fragment file`) + dim(` — ${source}`));
+	lines.push("");
+	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):`));
@@ -535,30 +731,57 @@ function toUrl(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).
+* The validate command's pure core: run the requested pipeline over a local file or
+* public URL. `file:` is allowed in addition to http(s) so local YAML can be
+* validated (the web app deliberately stays http(s)-only). As an authoring tool, the
+* tutor path runs the THOROUGH check (`validateLibraries`), so every fragment in every
+* referenced library is rendered — not just the ones the tutor uses.
 */
-function runValidate(pathOrUrl) {
-	return loadAndBuildTutorPrompt(toUrl(pathOrUrl), cliFetcher, { allowedSchemes: [
+function runValidate(pathOrUrl, kind) {
+	const url = toUrl(pathOrUrl);
+	const allowedSchemes = [
 		"http:",
 		"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
+	}));
 }
 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;
+	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", `
+Examples:
+  # Validate a tutor (also strict-renders every fragment in every referenced library)
+  $ novedu-cli validate ./tutors/my-tutor.yaml
+
+  # Validate a fragment library on its own
+  $ novedu-cli validate ./tutors/my-fragments.yaml --kind fragment
+
+  # 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".`);
+			process.exitCode = 1;
+			return;
+		}
+		const outcome = await runValidate(pathOrUrl, options.kind === "fragment" ? "fragment" : "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));
+		process.exitCode = outcome.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");
+program.name("novedu-cli").description("Command-line companion for the Novedu chat app").version("0.2.0");
 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.1.2",
-  "description": "Command-line companion for the Novedu chat app. Validates tutor YAML definitions (more commands to follow).",
+  "version": "0.3.0",
+  "description": "Command-line companion for the Novedu chat app. Validates tutor YAML definitions and fragment libraries (more commands to follow).",
   "type": "module",
   "repository": {
     "type": "git",