@novedu/cli 0.2.0 → 0.3.1

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";
@@ -40,6 +41,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. */
@@ -635,6 +656,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) {
@@ -652,7 +687,7 @@ 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):`));
@@ -677,7 +712,7 @@ function formatFragmentResult(result, source) {
 	lines.push(red(`✘ Invalid fragment file`) + 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):`));
@@ -723,7 +758,16 @@ function runValidate(pathOrUrl, kind) {
 	}));
 }
 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").action(async (pathOrUrl, options) => {
+	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;
@@ -737,8 +781,9 @@ function registerValidate(program) {
 }
 //#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,6 +1,6 @@
 {
   "name": "@novedu/cli",
-  "version": "0.2.0",
+  "version": "0.3.1",
   "description": "Command-line companion for the Novedu chat app. Validates tutor YAML definitions and fragment libraries (more commands to follow).",
   "type": "module",
   "repository": {