@novedu/cli 0.4.0 → 0.5.1

package/README.md

@@ -1,33 +1,40 @@
 # @novedu/cli
 
 Command-line companion for the Novedu chat app (installed command: `novedu-cli`).
-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.
+Today it validates every activity YAML the app accepts — **tutors**, **fragment
+libraries**, **quizzes**, **writing activities**, and **coding activities**; more
+commands will follow. Validating a tutor also fully validates every fragment library
+it references; pass `--kind` to validate any other kind 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.
+It reuses the app's exact validation pipeline (`lib/tutors`, `lib/quiz-validate`,
+`lib/writing-validate`, `lib/coding-validate`), so an activity that passes here is
+the same one 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
+npx @novedu/cli validate ./activities/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
+npx @novedu/cli validate https://raw.githubusercontent.com/Teaching-HTL-Leonding/novedu-chat-mvp/refs/heads/main/activities/tutors/simple-tutor.yaml
 
 # Validate a fragment library on its own
-npx @novedu/cli validate ./tutors/simple-fragments.yaml --kind fragment
+npx @novedu/cli validate ./activities/tutors/simple-fragments.yaml --kind fragment
+
+# Validate a quiz, a writing activity, or a coding activity
+npx @novedu/cli validate ./activities/quizzes/sample-quiz.yaml --kind quiz
+npx @novedu/cli validate ./activities/writings/human-animal-short-story.yaml --kind writing
+npx @novedu/cli validate ./activities/coding/beginner-typescript.yaml --kind coding
 
 # Machine-readable output (the raw validation result)
-npx @novedu/cli validate ./tutors/simple-tutor.yaml --json
+npx @novedu/cli validate ./activities/tutors/simple-tutor.yaml --json
 ```
 
-`--kind` defaults to `tutor`; it is caller-declared, not auto-detected.
+`--kind` accepts `tutor` (default), `fragment`, `quiz`, `writing`, or `coding`; 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
+Exit code is `0` when the activity is valid and `1` when it has errors, so it works
 as a pre-commit / CI gate.
 
 ## Development
@@ -35,7 +42,7 @@ as a pre-commit / CI gate.
 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 -- validate ./activities/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)
 ```

package/dist/main.js

@@ -446,7 +446,7 @@ function resolveRelativeUrl(ref, baseUrl) {
 * 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`,
+* next to `.../activities/tutors/linked-list-tutor.yaml` becomes `.../activities/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.
 */
@@ -628,6 +628,52 @@ async function loadAndCheckFragmentFile(url, fetchImpl, opts = {}) {
 	return checkFragmentFileValue(yaml.value, url);
 }
 //#endregion
+//#region ../lib/coding-schema.ts
+const CodingYamlSchema = z.strictObject({
+	id: z.string().min(1),
+	name: z.string().optional(),
+	title: z.string().optional(),
+	llm: z.strictObject({ model: z.string().min(1) }),
+	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.
+*/
+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;
+	return {
+		ok: true,
+		codingId: coding.id,
+		model: coding.llm.model,
+		title: coding.title ?? null,
+		warnings: []
+	};
+}
+/**
+* Validate a coding FILE: scheme-gate + fetch + parse (shared `loadYaml`), then the
+* pure `checkCodingValue`. The web app passes the default http(s)-only schemes; the
+* CLI adds `file:` so a local coding YAML on disk validates too.
+*/
+async function loadAndCheckCoding(url, fetchImpl, opts = {}) {
+	const yaml = await loadYaml(url, fetchImpl, opts);
+	if (!yaml.ok) return {
+		ok: false,
+		errors: [yaml.error],
+		warnings: []
+	};
+	return checkCodingValue(yaml.value, url);
+}
+//#endregion
 //#region ../lib/quiz-schema.ts
 /** An optional content image attached to a question (carries no secret). */
 const ImageRefSchema = z.strictObject({
@@ -920,6 +966,24 @@ function formatWritingResult(result, source) {
 	}
 	return lines.join("\n");
 }
+/**
+* Renderer for a coding-activity check (`--kind coding`). Coding is ALWAYS anonymous
+* (the API path carries no per-student identity), so — unlike quiz/writing — that is
+* shown as a fixed note, not a per-file value.
+*/
+function formatCodingResult(result, source) {
+	if (!result.ok) return renderFailureAndWarnings(result, "coding activity", source);
+	const lines = [green(`✔ Valid coding activity`) + dim(` — ${source}`)];
+	lines.push(`  id: ${result.codingId}`);
+	lines.push(`  model: ${result.model}`);
+	lines.push(`  anonymous: true ${dim("(always — the API path carries no identity)")}`);
+	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). */
@@ -927,7 +991,8 @@ const VALIDATE_KINDS = [
 	"tutor",
 	"fragment",
 	"quiz",
-	"writing"
+	"writing",
+	"coding"
 ];
 /**
 * Turn the CLI argument into a URL the tutor core understands: an http(s) URL is
@@ -965,6 +1030,10 @@ function runValidate(pathOrUrl, kind) {
 			kind,
 			result
 		}));
+		case "coding": return loadAndCheckCoding(url, cliFetcher, { allowedSchemes }).then((result) => ({
+			kind,
+			result
+		}));
 		default: return loadAndBuildTutorPrompt(url, cliFetcher, {
 			allowedSchemes,
 			validateLibraries: true
@@ -975,17 +1044,18 @@ function runValidate(pathOrUrl, kind) {
 	}
 }
 function registerValidate(program) {
-	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", `
+	program.command("validate").description("Validate a tutor (default), fragment library, quiz, writing or coding YAML by local path or public http(s) URL").argument("<pathOrUrl>", "path to a tutor, fragment, quiz, writing or coding 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
+  $ novedu-cli validate ./activities/tutors/my-tutor.yaml
 
   # Validate a fragment library on its own
-  $ novedu-cli validate ./tutors/my-fragments.yaml --kind fragment
+  $ novedu-cli validate ./activities/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
+  # Validate a quiz, a writing activity, or a coding activity
+  $ novedu-cli validate ./activities/quizzes/my-quiz.yaml --kind quiz
+  $ novedu-cli validate ./activities/writings/my-writing.yaml --kind writing
+  $ novedu-cli validate ./activities/coding/my-coding.yaml --kind coding
 
   # Machine-readable output for CI
   $ novedu-cli validate https://example.com/tutor.yaml --json`).action(async (pathOrUrl, options) => {
@@ -1006,6 +1076,7 @@ function formatOutcome(outcome, source) {
 		case "fragment": return formatFragmentResult(outcome.result, source);
 		case "quiz": return formatQuizResult(outcome.result, source);
 		case "writing": return formatWritingResult(outcome.result, source);
+		case "coding": return formatCodingResult(outcome.result, source);
 		default: return formatResult(outcome.result, source);
 	}
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@novedu/cli",
-  "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).",
+  "version": "0.5.1",
+  "description": "Command-line companion for the Novedu chat app. Validates tutor, fragment, quiz, writing and coding YAML definitions (more commands to follow).",
   "type": "module",
   "repository": {
     "type": "git",
@@ -31,6 +31,6 @@
     "zod": "^4.4.3"
   },
   "devDependencies": {
-    "tsdown": "^0.22.2"
+    "tsdown": "^0.22.3"
   }
 }