@novedu/cli 0.9.0 → 0.11.0

package/dist/main.js

@@ -186,7 +186,7 @@ function displayName(result) {
 }
 //#endregion
 //#region src/server-url.ts
-const DEFAULT_SERVER = "https://novedu-chat-mvp-at.azurewebsites.net";
+const DEFAULT_SERVER = "https://novedu.at";
 function resolveServerUrl(cliOption) {
 	return cliOption || process.env.NOVEDU_SERVER || DEFAULT_SERVER;
 }
@@ -610,66 +610,106 @@ function validate(value, schema, code, url) {
 * 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.
+*
+* The `.refine()` is the RUNTIME enforcement. `z.toJSONSchema()` cannot derive a pattern
+* from a refinement, so the equivalent editor constraint is re-expressed via `.meta({ pattern })`
+* — the two MUST be kept consistent (both mean "http(s) URL or a scheme-less relative path").
 */
-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" });
+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" }).meta({
+	pattern: "^(https?://|(?![A-Za-z][A-Za-z0-9+.-]*:).+)$",
+	description: "HTTP(S) URL or relative path to the fragment library."
+});
 /**
 * 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 activity omits the variable, the default is used; supplying
 * a value overrides it. See `consistency.ts` for where defaults are injected.
 */
+const StringPropertySchema = z.strictObject({
+	type: z.literal("string").meta({ description: "Declares a string variable." }),
+	default: z.string().optional().meta({ description: "Default string used when the activity omits this variable." })
+}).meta({
+	id: "stringProperty",
+	description: "A string variable, with an optional default."
+});
+const BooleanPropertySchema = z.strictObject({
+	type: z.literal("boolean").meta({ description: "Declares a boolean variable." }),
+	default: z.boolean().optional().meta({ description: "Default boolean used when the activity omits this variable." })
+}).meta({
+	id: "booleanProperty",
+	description: "A boolean variable, with an optional default."
+});
+const StringArrayPropertySchema = z.strictObject({
+	type: z.literal("array").meta({ description: "Declares an array-of-strings variable." }),
+	items: z.strictObject({ type: z.literal("string").meta({ description: "Array elements are strings." }) }).meta({ description: "The element type of the array (always string)." }),
+	default: z.array(z.string()).optional().meta({ description: "Default string array used when the activity omits this variable." })
+}).meta({
+	id: "stringArrayProperty",
+	description: "An array-of-strings variable, with an optional default."
+});
 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()
-	})
-]);
+	StringPropertySchema,
+	BooleanPropertySchema,
+	StringArrayPropertySchema
+]).meta({
+	id: "inputProperty",
+	description: "A declared variable: a string, a boolean, or an array of strings, each with an optional matching default."
+});
 const InputSchema = z.strictObject({
-	type: z.literal("object"),
-	required: z.array(z.string()).default([]),
-	properties: z.record(z.string(), PropertySchema).default({})
+	type: z.literal("object").meta({ description: "Always \"object\"." }),
+	required: z.array(z.string()).default([]).meta({ description: "Names of the variables that must be supplied." }),
+	properties: z.record(z.string(), PropertySchema).default({}).meta({ description: "The declared variables, keyed by variable name." })
+}).meta({
+	id: "inputSchema",
+	description: "A constrained mini JSON-schema declaring the variables a fragment accepts."
 });
 const ClassificationSchema = z.strictObject({
-	type: z.string(),
-	override_allowed: z.boolean().optional()
+	type: z.string().meta({ description: "Classification label for this fragment." }),
+	override_allowed: z.boolean().optional().meta({ description: "Whether an activity may override this classification." })
+}).meta({
+	id: "classification",
+	description: "Optional classification metadata for a fragment."
 });
 const FragmentSchema = z.strictObject({
-	id: z.string(),
-	version: z.number(),
-	priority: z.number(),
+	id: z.string().meta({ description: "Unique fragment id within this library." }),
+	version: z.number().meta({ description: "Fragment version number." }),
+	priority: z.number().meta({ description: "Assembly order. Lower priorities appear earlier." }),
 	input_schema: InputSchema.optional(),
 	classification: ClassificationSchema.optional(),
-	content: z.string()
+	content: z.string().meta({ description: "Prompt text as a Handlebars template." })
+}).meta({
+	id: "fragment",
+	description: "One reusable, parameterized prompt fragment."
 });
 const FragmentFileSchema = z.strictObject({
-	id: z.string(),
-	fragments: z.array(FragmentSchema).min(1)
+	id: z.string().meta({ description: "Machine-readable id of this fragment library." }),
+	fragments: z.array(FragmentSchema).min(1).meta({ description: "The reusable fragments this library provides (at least one)." })
 });
 /** A supplied variable value mirrors what `input_schema` can declare. */
 const VariableValueSchema = z.union([
 	z.string(),
 	z.boolean(),
 	z.array(z.string())
-]);
+]).meta({
+	id: "variableValue",
+	description: "A literal variable value: a string, a boolean, or an array of strings."
+});
 const FragmentFileRefSchema = z.strictObject({
-	id: z.string(),
+	id: z.string().meta({ description: "Local alias for this library, referenced by each fragment's `file`." }),
 	url: FragmentUrlRef
+}).meta({
+	id: "fragmentFileRef",
+	description: "A reference to a fragment library by alias + URL."
 });
 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()
+	file: z.string().meta({ description: "The alias of the fragment library this fragment is drawn from." }),
+	id: z.string().meta({ description: "Fragment id inside the referenced library." }),
+	variables: z.record(z.string(), VariableValueSchema).optional().meta({ description: "Literal values passed into the fragment template." }),
+	bind: z.record(z.string(), z.string()).optional().meta({ description: "Accepted for compatibility but ignored by the current assembler." }),
+	required: z.boolean().optional().meta({ description: "Marker for important fragments. Accepted but not currently enforced." })
+}).meta({
+	id: "fragmentRef",
+	description: "Selects one fragment from a referenced library."
 });
 //#endregion
 //#region ../lib/prompt-fragments/fragment.ts
@@ -978,20 +1018,23 @@ async function loadAndCheckFragmentFile(url, fetchImpl, opts = {}) {
 	};
 	return checkFragmentFileValue(yaml.value, url);
 }
-const providerSchema = z.enum(["SCCH", "Azure Foundry"]).default("SCCH");
+const providerSchema = z.enum(["SCCH", "Azure Foundry"]).default("SCCH").meta({ description: "The LLM provider serving the model. For Azure Foundry, model is the deployment name." });
 //#endregion
 //#region ../lib/coding-schema.ts
 const CodingYamlSchema = z.strictObject({
-	id: z.string().min(1),
-	name: z.string().optional(),
-	title: z.string().optional(),
+	id: z.string().min(1).meta({ description: "Short machine-readable activity id, e.g. beginner-typescript." }),
+	name: z.string().optional().meta({ description: "Optional human-readable label (not shown to the student)." }),
+	title: z.string().optional().meta({ description: "Optional label shown to the student on the /<code> connection page." }),
 	llm: z.strictObject({
-		model: z.string().min(1),
+		model: z.string().min(1).meta({ description: "The model that answers. SERVER-ONLY and PINNED: the proxy always uses this model and ignores whatever model the coding agent sends." }),
 		provider: providerSchema
+	}).meta({
+		id: "llm",
+		description: "The pinned model and provider that answer coding requests."
 	}),
-	fragment_files: z.array(FragmentFileRefSchema).default([]),
-	fragments: z.array(FragmentRefSchema).default([]),
-	instructions: z.string().min(1)
+	fragment_files: z.array(FragmentFileRefSchema).default([]).meta({ description: "Optional fragment libraries this activity pulls shared prompt fragments from." }),
+	fragments: z.array(FragmentRefSchema).default([]).meta({ description: "Optional fragments selected from fragment_files. Assembled in priority order and prepended AHEAD of instructions." }),
+	instructions: z.string().min(1).meta({ description: "The assistant's system prompt. SERVER-ONLY: never sent to the browser or the coding agent, and appended AFTER the coding tool's own prompt (so the teacher has the final word). Constrain the assistant to what your class has learned." })
 });
 //#endregion
 //#region ../lib/coding-validate.ts
@@ -1052,10 +1095,16 @@ async function loadAndCheckCoding(url, fetchImpl, opts = {}) {
 //#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()
+	hosted: z.boolean().optional().meta({
+		default: false,
+		description: "When true, src is an app-hosted image NAME resolved server-side; otherwise src is an absolute URL or a path relative to the quiz's own URL."
+	}),
+	src: z.string().min(1).meta({ description: "The hosted image name (when hosted) or the image URL / relative path." }),
+	alt: z.string().optional().meta({ description: "Accessible description shown if the image cannot be loaded." }),
+	credit: z.string().optional().meta({ description: "Optional attribution (\"Content Credentials\") shown small below the image." })
+}).meta({
+	id: "image",
+	description: "An optional content image attached to a question."
 });
 /**
 * One question. `id` keys the per-question stats (must be unique — see
@@ -1063,29 +1112,47 @@ const ImageRefSchema = z.strictObject({
 * `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),
+	id: z.string().min(1).meta({ description: "Stable question id, unique within the quiz (the per-question stats key)." }),
+	title: z.string().optional().meta({ description: "Optional short label for the stats table and progress display." }),
+	question: z.string().min(1).meta({ description: "The Markdown shown to the student." }),
+	evaluation: z.string().min(1).meta({ description: "The grading prompt. SERVER-ONLY: never sent to the browser, so it may embed the expected answer and the grading rubric." }),
 	image: ImageRefSchema.optional(),
-	imageInput: z.boolean().optional()
+	imageInput: z.boolean().optional().meta({ description: "Overrides the quiz-level llm.imageInput for this question only (photo answers on/off)." })
+}).meta({
+	id: "question",
+	description: "One open-ended, LLM-graded quiz question."
 });
 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(),
+	id: z.string().min(1).meta({ description: "Short machine-readable quiz id, e.g. countries-basics. Used as the per-quiz identity." }),
+	name: z.string().optional().meta({ description: "Optional human-readable quiz title (used as a label)." }),
+	title: z.string().optional().meta({ description: "Optional greeting shown to students on the welcome screen instead of the default message." }),
+	description: z.string().optional().meta({ description: "Optional description shown to students below the welcome greeting (Markdown)." }),
+	anonymous: z.boolean().optional().meta({
+		default: true,
+		description: "Quizzes are anonymous by default: answers are recorded for aggregate stats but not linked to a student. Set to false to attribute each attempt to the signed-in student."
+	}),
+	shuffle: z.boolean().optional().meta({
+		default: true,
+		description: "Present questions in a random order per attempt. Set to false to keep the authored order."
+	}),
 	llm: z.strictObject({
-		model: z.string().min(1),
+		model: z.string().min(1).meta({ description: "The model that grades answers and drives the per-question discussion chat." }),
 		provider: providerSchema,
-		imageInput: z.boolean().optional()
+		imageInput: z.boolean().optional().meta({
+			default: false,
+			description: "Default for all questions: students may attach photos (up to 3, 5 MB each) to their answers. The model must be vision-capable. A per-question imageInput overrides it."
+		})
+	}).meta({
+		id: "llm",
+		description: "The single model + provider that grades and discusses answers."
 	}),
-	discussion: z.strictObject({ instructions: z.string().min(1) }).optional(),
-	fragment_files: z.array(FragmentFileRefSchema).default([]),
-	fragments: z.array(FragmentRefSchema).default([]),
-	questions: z.array(QuizQuestionSchema).min(1)
+	discussion: z.strictObject({ instructions: z.string().min(1).meta({ description: "Optional guidance appended to the per-question follow-up discussion chat's system prompt." }) }).optional().meta({
+		id: "discussion",
+		description: "Optional guidance for the per-question follow-up discussion chat."
+	}),
+	fragment_files: z.array(FragmentFileRefSchema).default([]).meta({ description: "Optional fragment libraries this quiz pulls shared prompt fragments from." }),
+	fragments: z.array(FragmentRefSchema).default([]).meta({ description: "Optional fragments selected from fragment_files. Assembled in priority order and prepended to BOTH the grader prompt and the discussion chat's system prompt." }),
+	questions: z.array(QuizQuestionSchema).min(1).meta({ description: "The quiz questions. Each is open-ended and graded by the LLM via its evaluation prompt." })
 });
 //#endregion
 //#region ../lib/quiz-validate.ts
@@ -1175,25 +1242,40 @@ async function loadAndCheckQuiz(url, fetchImpl, opts = {}) {
 * 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)
+	title: z.string().min(1).meta({ description: "Short clickable label shown on the welcome screen." }),
+	question: z.string().min(1).meta({ description: "Full question text. Shown as a tooltip and placed into the chat input on click." })
+}).meta({
+	id: "exampleQuestion",
+	description: "An example question shown on the welcome screen."
 });
 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(),
+	id: z.string().meta({ description: "Short machine-readable tutor id, e.g. fractions-de." }),
+	name: z.string().meta({ description: "Human-readable tutor title." }),
+	title: z.string().optional().meta({ description: "Optional greeting shown to students on the empty chat instead of the default welcome message." }),
+	description: z.string().meta({ description: "Short description of what this tutor does. Shown to students below the welcome greeting." }),
+	exampleQuestions: z.array(ExampleQuestionSchema).optional().meta({ description: "Optional example questions shown to students below the description on the empty chat. Clicking one puts the question text into the chat input. At most 5 are shown; with more, a random 5 are picked per page load." }),
+	anonymous: z.boolean().optional().meta({
+		default: true,
+		description: "Chats are anonymous by default: no link between the signed-in student and their chat is stored. Set to false to record which student each chat belongs to."
+	}),
 	llm: z.strictObject({
-		model: z.string(),
+		model: z.string().meta({ description: "Model used for this tutor." }),
 		provider: providerSchema,
-		imageInput: z.boolean().optional()
+		imageInput: z.boolean().optional().meta({
+			default: true,
+			description: "Image uploads are enabled by default. Set to false to hide the upload UI for text-only tutors or non-vision-capable models."
+		})
+	}).meta({
+		id: "llm",
+		description: "The model and provider that back this tutor."
 	}),
 	prompt: z.strictObject({
-		fragment_files: z.array(FragmentFileRefSchema).default([]),
-		fragments: z.array(FragmentRefSchema).default([]),
-		tutor_instructions: z.string()
+		fragment_files: z.array(FragmentFileRefSchema).default([]).meta({ description: "Optional fragment libraries used by this tutor." }),
+		fragments: z.array(FragmentRefSchema).default([]).meta({ description: "Optional fragments selected from fragment_files." }),
+		tutor_instructions: z.string().meta({ description: "Final tutor-specific system-prompt instructions. For single-file tutors, this can be the whole prompt." })
+	}).meta({
+		id: "prompt",
+		description: "The assembled system prompt: fragments plus tutor instructions."
 	})
 });
 //#endregion
@@ -1236,19 +1318,25 @@ async function loadAndBuildTutorPrompt(url, fetchImpl, opts = {}) {
 //#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(),
+	id: z.string().min(1).meta({ description: "Short machine-readable activity id, e.g. human-animal-short-story." }),
+	name: z.string().optional().meta({ description: "Optional human-readable title (used as a label)." }),
+	title: z.string().optional().meta({ description: "Optional greeting shown to students on the welcome screen instead of the default message." }),
+	description: z.string().optional().meta({ description: "Optional description shown to students below the welcome greeting (Markdown)." }),
+	anonymous: z.boolean().optional().meta({
+		default: false,
+		description: "Writing DIVERGES: it defaults to false (attributed), because review and the Save feature need to know whose text it is. Set to true for ephemeral, unattributed writing — which also disables saving."
+	}),
 	llm: z.strictObject({
-		model: z.string().min(1),
+		model: z.string().min(1).meta({ description: "The model that drives the feedback chat." }),
 		provider: providerSchema
+	}).meta({
+		id: "llm",
+		description: "The model and provider that back the writing coach."
 	}),
-	fragment_files: z.array(FragmentFileRefSchema).default([]),
-	fragments: z.array(FragmentRefSchema).default([]),
-	instructions: z.string().min(1),
-	placeholder: z.string().optional()
+	fragment_files: z.array(FragmentFileRefSchema).default([]).meta({ description: "Optional fragment libraries this activity pulls shared prompt fragments from." }),
+	fragments: z.array(FragmentRefSchema).default([]).meta({ description: "Optional fragments selected from fragment_files. Assembled in priority order and prepended AHEAD of instructions." }),
+	instructions: z.string().min(1).meta({ description: "The writing coach's system prompt. SERVER-ONLY: never sent to the browser, so it may describe the assessment criteria and coaching strategy." }),
+	placeholder: z.string().optional().meta({ description: "Optional starter text prefilled into the editor. Empty for a blank page." })
 });
 //#endregion
 //#region ../lib/writing-validate.ts

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@novedu/cli",
-  "version": "0.9.0",
+  "version": "0.11.0",
   "description": "Command-line companion for the Novedu chat app. Validates tutor, fragment, quiz, writing and coding YAML definitions; signs in with Entra ID and manages codes and app-hosted files over the app's API.",
   "type": "module",
   "repository": {