@novedu/cli 0.8.0 → 0.9.0

package/dist/main.js

@@ -358,25 +358,34 @@ Purely local — already-issued access tokens stay valid until they expire
 	});
 }
 //#endregion
-//#region ../lib/tutors/assemble.ts
+//#region ../lib/prompt-fragments/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.
+* Render each fragment in priority order and, when provided, append the caller's
+* trailing instructions last (they carry no priority, so "after everything" is the
+* only deterministic position — the exact role `tutor_instructions` plays for a
+* tutor, and the activity frame / `instructions` play for quiz / writing / coding).
+* May throw if a template references a missing variable.
+*
+* `trailingInstructions` is optional so a consumer can assemble a fragment-only
+* PREAMBLE (quiz / writing / coding) and concatenate its own frame afterwards. An
+* empty plan with no trailing text renders to the empty string (so an activity that
+* declares no fragments gets no stray whitespace); every non-empty result ends in a
+* single trailing newline, byte-identical to the historic tutor output.
 */
-function assembleSystemPrompt(plan, tutor) {
+function assembleSystemPrompt(plan, trailingInstructions) {
 	const parts = plan.map((fragment) => {
 		return Handlebars.compile(fragment.content, COMPILE_OPTIONS)(fragment.variables).trimEnd();
 	});
-	parts.push(tutor.prompt.tutor_instructions.trimEnd());
+	if (trailingInstructions !== void 0) parts.push(trailingInstructions.trimEnd());
+	if (parts.length === 0) return "";
 	return `${parts.join("\n\n")}\n`;
 }
 //#endregion
-//#region ../lib/tutors/errors.ts
+//#region ../lib/prompt-fragments/errors.ts
 /** Small helper to build an error object tersely at call sites. */
 function error(code, message, extra = {}) {
 	return {
@@ -413,7 +422,7 @@ function formatZodIssues(zodIssues) {
 	return out;
 }
 //#endregion
-//#region ../lib/tutors/consistency.ts
+//#region ../lib/prompt-fragments/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;
@@ -432,11 +441,11 @@ function typeMismatch(prop, value) {
 		};
 	}
 }
-function checkConsistency(tutor, fragmentFilesByAlias) {
+function checkConsistency(block, 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 ref of block.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) {
@@ -455,7 +464,7 @@ function checkConsistency(tutor, fragmentFilesByAlias) {
 	}
 	const resolved = [];
 	const seenRefs = /* @__PURE__ */ new Set();
-	for (const ref of tutor.prompt.fragments) {
+	for (const ref of block.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,
@@ -547,7 +556,7 @@ function checkConsistency(tutor, fragmentFilesByAlias) {
 	};
 }
 //#endregion
-//#region ../lib/tutors/fetcher.ts
+//#region ../lib/prompt-fragments/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) => {
@@ -563,7 +572,7 @@ const defaultFetcher = async (url) => {
 	}
 };
 //#endregion
-//#region ../lib/tutors/parse.ts
+//#region ../lib/prompt-fragments/parse.ts
 /** Parse a YAML document, mapping syntax errors to a structured `YAML_PARSE_ERROR`. */
 function parseYaml(text, url) {
 	try {
@@ -593,12 +602,11 @@ function validate(value, schema, code, url) {
 		})
 	};
 }
-const providerSchema = z.enum(["SCCH", "Azure Foundry"]).default("SCCH");
 //#endregion
-//#region ../lib/tutors/schemas.ts
+//#region ../lib/prompt-fragments/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
+* `load.ts` resolves against the activity 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.
@@ -607,7 +615,7 @@ const FragmentUrlRef = z.string().min(1).refine((u) => !/^[a-z][a-z0-9+.-]*:/i.t
 /**
 * 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
+* 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 PropertySchema = z.discriminatedUnion("type", [
@@ -663,35 +671,8 @@ const FragmentRefSchema = z.strictObject({
 	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(),
-		provider: providerSchema,
-		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/fragment.ts
+//#region ../lib/prompt-fragments/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
@@ -794,17 +775,17 @@ function resolveRelativeUrl(ref, baseUrl) {
 	return new URL(ref, baseUrl).href;
 }
 //#endregion
-//#region ../lib/tutors/load.ts
+//#region ../lib/prompt-fragments/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 `my-fragments.yaml`
+* as-is; anything else is treated as relative to the activity URL — standard URL resolution
+* drops the activity's filename and appends the relative path (so `my-fragments.yaml`
 * next to `.../tutors/my-tutor.yaml` becomes `.../tutors/my-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) {
-	return resolveRelativeUrl(ref, tutorUrl);
+function resolveFragmentUrl(ref, baseUrl) {
+	return resolveRelativeUrl(ref, baseUrl);
 }
 async function fetchText(url, fetchImpl) {
 	try {
@@ -829,23 +810,33 @@ async function fetchText(url, fetchImpl) {
 }
 const DEFAULT_ALLOWED_SCHEMES = ["http:", "https:"];
 /**
-* 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, the
-* standalone fragment checker, and the quiz/writing validators so they all gate
-* schemes identically.
+* The SSRF scheme gate shared by the top-level activity load (`loadYaml`) and every
+* fragment-file fetch (`assembleFragmentPrompt`): a URL is allowed only if its scheme
+* is in `allowedSchemes` (default http(s); the CLI adds `file:` for on-disk validation).
+* Returns the structured error to surface, or `null` when the scheme is allowed.
 */
-async function loadYaml(url, fetchImpl, opts = {}) {
-	const allowedSchemes = opts.allowedSchemes ?? DEFAULT_ALLOWED_SCHEMES;
+function schemeGate(url, allowedSchemes) {
 	let scheme;
 	try {
 		scheme = new URL(url).protocol;
 	} catch {
 		scheme = "";
 	}
-	if (!allowedSchemes.includes(scheme)) return {
+	if (allowedSchemes.includes(scheme)) return null;
+	return error("INVALID_URL", `Provide a valid ${allowedSchemes.map((s) => s.replace(/:$/, "")).join("/")} URL`, { url });
+}
+/**
+* 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 activity builders, the
+* standalone fragment checker, and the quiz/writing/coding validators so they all gate
+* schemes identically.
+*/
+async function loadYaml(url, fetchImpl, opts = {}) {
+	const schemeError = schemeGate(url, opts.allowedSchemes ?? DEFAULT_ALLOWED_SCHEMES);
+	if (schemeError) return {
 		ok: false,
-		error: error("INVALID_URL", `Provide a valid ${allowedSchemes.map((s) => s.replace(/:$/, "")).join("/")} URL`, { url })
+		error: schemeError
 	};
 	const fetched = await fetchText(url, fetchImpl);
 	if (!fetched.ok) return {
@@ -862,25 +853,30 @@ async function loadYaml(url, fetchImpl, opts = {}) {
 		value: parsed.value
 	};
 }
-async function loadAndBuildTutorPrompt(url, fetchImpl, opts = {}) {
+/**
+* Resolve a document-level fragment block to a finished prompt string: fetch every
+* declared fragment file in parallel (relative refs resolved against `baseUrl`),
+* schema-validate each, (optionally) run the thorough whole-library check, check
+* consistency, and assemble the priority-ordered plan followed by the optional
+* `trailingInstructions`.
+*
+* The single seam every activity kind shares — the sole owner of the fetch → validate
+* → consistency → assemble pipeline. Consumers concatenate their own frame only when
+* they pass no `trailingInstructions` (a fragment-only preamble); tutors pass their
+* `tutor_instructions` and get a complete prompt.
+*/
+async function assembleFragmentPrompt(block, baseUrl, fetchImpl, opts = {}, trailingInstructions) {
 	const warnings = [];
-	const tutorYaml = await loadYaml(url, fetchImpl, opts);
-	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],
+	const allowedSchemes = opts.allowedSchemes ?? DEFAULT_ALLOWED_SCHEMES;
+	if (block.fragment_files.length === 0 && block.fragments.length === 0) return {
+		ok: true,
+		prompt: assembleSystemPrompt([], trailingInstructions),
 		warnings
 	};
-	const tutor = tutorValid.data;
-	const settled = await Promise.all(tutor.prompt.fragment_files.map(async (ref) => {
+	const settled = await Promise.all(block.fragment_files.map(async (ref) => {
 		let fragmentUrl;
 		try {
-			fragmentUrl = resolveFragmentUrl(ref.url, url);
+			fragmentUrl = resolveFragmentUrl(ref.url, baseUrl);
 		} catch {
 			return {
 				alias: ref.id,
@@ -890,6 +886,14 @@ async function loadAndBuildTutorPrompt(url, fetchImpl, opts = {}) {
 				})
 			};
 		}
+		const schemeError = schemeGate(fragmentUrl, allowedSchemes);
+		if (schemeError) return {
+			alias: ref.id,
+			error: {
+				...schemeError,
+				fileAlias: ref.id
+			}
+		};
 		const fetched = await fetchText(fragmentUrl, fetchImpl);
 		if (!fetched.ok) return {
 			alias: ref.id,
@@ -936,7 +940,7 @@ async function loadAndBuildTutorPrompt(url, fetchImpl, opts = {}) {
 		libraryErrors.push(...checked.errors);
 		warnings.push(...checked.warnings);
 	}
-	const consistency = checkConsistency(tutor, fragmentFilesByAlias);
+	const consistency = checkConsistency(block, fragmentFilesByAlias);
 	warnings.push(...consistency.warnings);
 	const preAssemblyErrors = [...libraryErrors, ...consistency.errors];
 	if (preAssemblyErrors.length > 0) return {
@@ -947,14 +951,7 @@ async function loadAndBuildTutorPrompt(url, fetchImpl, opts = {}) {
 	try {
 		return {
 			ok: true,
-			prompt: assembleSystemPrompt(consistency.plan, tutor),
-			model: tutor.llm.model,
-			provider: tutor.llm.provider,
-			imageInput: tutor.llm.imageInput ?? true,
-			anonymous: tutor.anonymous ?? true,
-			title: tutor.title,
-			description: tutor.description,
-			exampleQuestions: tutor.exampleQuestions ?? [],
+			prompt: assembleSystemPrompt(consistency.plan, trailingInstructions),
 			warnings
 		};
 	} catch (e) {
@@ -968,9 +965,9 @@ 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
+* fragment library is self-contained, so — unlike an activity — 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).
+* a `FragmentCheckResult` directly (no activity `BuildResult`, no kind discriminator).
 */
 async function loadAndCheckFragmentFile(url, fetchImpl, opts = {}) {
 	const yaml = await loadYaml(url, fetchImpl, opts);
@@ -981,6 +978,7 @@ async function loadAndCheckFragmentFile(url, fetchImpl, opts = {}) {
 	};
 	return checkFragmentFileValue(yaml.value, url);
 }
+const providerSchema = z.enum(["SCCH", "Azure Foundry"]).default("SCCH");
 //#endregion
 //#region ../lib/coding-schema.ts
 const CodingYamlSchema = z.strictObject({
@@ -991,23 +989,18 @@ const CodingYamlSchema = z.strictObject({
 		model: z.string().min(1),
 		provider: providerSchema
 	}),
+	fragment_files: z.array(FragmentFileRefSchema).default([]),
+	fragments: z.array(FragmentRefSchema).default([]),
 	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.
+* Extract metadata from an already-schema-validated coding value. Split from
+* `checkCodingValue` so `loadAndCheckCoding` can reuse the single `validate` it already
+* ran (no second parse of the same document against the same schema).
 */
-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;
+function checkCodingParsed(coding) {
 	return {
 		ok: true,
 		codingId: coding.id,
@@ -1029,7 +1022,31 @@ async function loadAndCheckCoding(url, fetchImpl, opts = {}) {
 		errors: [yaml.error],
 		warnings: []
 	};
-	return checkCodingValue(yaml.value, url);
+	const valid = validate(yaml.value, CodingYamlSchema, "CODING_SCHEMA_ERROR", url);
+	if (!valid.ok) return {
+		ok: false,
+		errors: [valid.error],
+		warnings: []
+	};
+	const checked = checkCodingParsed(valid.data);
+	if (!checked.ok) return checked;
+	const assembled = await assembleFragmentPrompt({
+		fragment_files: valid.data.fragment_files,
+		fragments: valid.data.fragments
+	}, url, fetchImpl, {
+		allowedSchemes: opts.allowedSchemes,
+		validateLibraries: opts.validateLibraries ?? true
+	});
+	const warnings = [...checked.warnings, ...assembled.warnings];
+	if (!assembled.ok) return {
+		ok: false,
+		errors: assembled.errors,
+		warnings
+	};
+	return {
+		...checked,
+		warnings
+	};
 }
 //#endregion
 //#region ../lib/quiz-schema.ts
@@ -1050,7 +1067,8 @@ const QuizQuestionSchema = z.strictObject({
 	title: z.string().optional(),
 	question: z.string().min(1),
 	evaluation: z.string().min(1),
-	image: ImageRefSchema.optional()
+	image: ImageRefSchema.optional(),
+	imageInput: z.boolean().optional()
 });
 const QuizYamlSchema = z.strictObject({
 	id: z.string().min(1),
@@ -1061,9 +1079,12 @@ const QuizYamlSchema = z.strictObject({
 	shuffle: z.boolean().optional(),
 	llm: z.strictObject({
 		model: z.string().min(1),
-		provider: providerSchema
+		provider: providerSchema,
+		imageInput: z.boolean().optional()
 	}),
 	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)
 });
 //#endregion
@@ -1084,18 +1105,11 @@ function findDuplicateQuestionIds(quiz) {
 	return errors;
 }
 /**
-* Validate an already-parsed quiz value: schema → unique question ids → metadata.
-* Pure (the parsed value is passed in); `loadAndCheckQuiz` wraps it with fetch +
-* YAML parse.
+* Check an already-schema-validated quiz: unique question ids → metadata. Split from
+* `checkQuizValue` so `loadAndCheckQuiz` can reuse the single `validate` it already ran
+* (no second parse of the same document against the same schema).
 */
-function checkQuizValue(parsed, url) {
-	const valid = validate(parsed, QuizYamlSchema, "QUIZ_SCHEMA_ERROR", url);
-	if (!valid.ok) return {
-		ok: false,
-		errors: [valid.error],
-		warnings: []
-	};
-	const quiz = valid.data;
+function checkQuizParsed(quiz) {
 	const errors = findDuplicateQuestionIds(quiz);
 	if (errors.length > 0) return {
 		ok: false,
@@ -1114,9 +1128,11 @@ function checkQuizValue(parsed, url) {
 	};
 }
 /**
-* Validate a quiz FILE: scheme-gate + fetch + parse (shared `loadYaml`), then the
-* pure `checkQuizValue`. The web app passes the default http(s)-only schemes; the
-* CLI adds `file:` so a local quiz YAML on disk validates too.
+* Validate a quiz FILE: scheme-gate + fetch + parse (shared `loadYaml`), the pure
+* `checkQuizValue`, then the document-level fragment block's authoring gate — fetch
+* every referenced library, run the THOROUGH whole-library check, consistency, and an
+* assembly dry-run (the strict-Handlebars backstop). The web app passes the default
+* http(s)-only schemes; the CLI adds `file:` so a local quiz YAML on disk validates too.
 */
 async function loadAndCheckQuiz(url, fetchImpl, opts = {}) {
 	const yaml = await loadYaml(url, fetchImpl, opts);
@@ -1125,7 +1141,97 @@ async function loadAndCheckQuiz(url, fetchImpl, opts = {}) {
 		errors: [yaml.error],
 		warnings: []
 	};
-	return checkQuizValue(yaml.value, url);
+	const valid = validate(yaml.value, QuizYamlSchema, "QUIZ_SCHEMA_ERROR", url);
+	if (!valid.ok) return {
+		ok: false,
+		errors: [valid.error],
+		warnings: []
+	};
+	const checked = checkQuizParsed(valid.data);
+	if (!checked.ok) return checked;
+	const assembled = await assembleFragmentPrompt({
+		fragment_files: valid.data.fragment_files,
+		fragments: valid.data.fragments
+	}, url, fetchImpl, {
+		allowedSchemes: opts.allowedSchemes,
+		validateLibraries: opts.validateLibraries ?? true
+	});
+	const warnings = [...checked.warnings, ...assembled.warnings];
+	if (!assembled.ok) return {
+		ok: false,
+		errors: assembled.errors,
+		warnings
+	};
+	return {
+		...checked,
+		warnings
+	};
+}
+//#endregion
+//#region ../lib/tutors/schemas.ts
+/**
+* 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(),
+		provider: providerSchema,
+		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
+async function loadAndBuildTutorPrompt(url, fetchImpl, opts = {}) {
+	const warnings = [];
+	const tutorYaml = await loadYaml(url, fetchImpl, opts);
+	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 assembled = await assembleFragmentPrompt(tutor.prompt, url, fetchImpl, opts, tutor.prompt.tutor_instructions);
+	warnings.push(...assembled.warnings);
+	if (!assembled.ok) return {
+		ok: false,
+		errors: assembled.errors,
+		warnings
+	};
+	return {
+		ok: true,
+		prompt: assembled.prompt,
+		model: tutor.llm.model,
+		provider: tutor.llm.provider,
+		imageInput: tutor.llm.imageInput ?? true,
+		anonymous: tutor.anonymous ?? true,
+		title: tutor.title,
+		description: tutor.description,
+		exampleQuestions: tutor.exampleQuestions ?? [],
+		warnings
+	};
 }
 //#endregion
 //#region ../lib/writing-schema.ts
@@ -1139,6 +1245,8 @@ const WritingYamlSchema = z.strictObject({
 		model: z.string().min(1),
 		provider: providerSchema
 	}),
+	fragment_files: z.array(FragmentFileRefSchema).default([]),
+	fragments: z.array(FragmentRefSchema).default([]),
 	instructions: z.string().min(1),
 	placeholder: z.string().optional()
 });
@@ -1147,18 +1255,11 @@ const WritingYamlSchema = z.strictObject({
 /** Writing DIVERGES from tutor/quiz: it defaults to attributed (`anonymous: false`). */
 const DEFAULT_ANONYMOUS = false;
 /**
-* Validate an already-parsed writing value against its schema, then extract metadata.
-* Pure (the parsed value is passed in); `loadAndCheckWriting` wraps it with fetch +
-* YAML parse.
+* Extract metadata from an already-schema-validated writing value. Split from
+* `checkWritingValue` so `loadAndCheckWriting` can reuse the single `validate` it already
+* ran (no second parse of the same document against the same schema).
 */
-function checkWritingValue(parsed, url) {
-	const valid = validate(parsed, WritingYamlSchema, "WRITING_SCHEMA_ERROR", url);
-	if (!valid.ok) return {
-		ok: false,
-		errors: [valid.error],
-		warnings: []
-	};
-	const writing = valid.data;
+function checkWritingParsed(writing) {
 	return {
 		ok: true,
 		writingId: writing.id,
@@ -1181,7 +1282,31 @@ async function loadAndCheckWriting(url, fetchImpl, opts = {}) {
 		errors: [yaml.error],
 		warnings: []
 	};
-	return checkWritingValue(yaml.value, url);
+	const valid = validate(yaml.value, WritingYamlSchema, "WRITING_SCHEMA_ERROR", url);
+	if (!valid.ok) return {
+		ok: false,
+		errors: [valid.error],
+		warnings: []
+	};
+	const checked = checkWritingParsed(valid.data);
+	if (!checked.ok) return checked;
+	const assembled = await assembleFragmentPrompt({
+		fragment_files: valid.data.fragment_files,
+		fragments: valid.data.fragments
+	}, url, fetchImpl, {
+		allowedSchemes: opts.allowedSchemes,
+		validateLibraries: opts.validateLibraries ?? true
+	});
+	const warnings = [...checked.warnings, ...assembled.warnings];
+	if (!assembled.ok) return {
+		ok: false,
+		errors: assembled.errors,
+		warnings
+	};
+	return {
+		...checked,
+		warnings
+	};
 }
 //#endregion
 //#region src/file-fetcher.ts

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@novedu/cli",
-  "version": "0.8.0",
+  "version": "0.9.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": {
@@ -25,13 +25,13 @@
     "prepublishOnly": "npm run build"
   },
   "dependencies": {
-    "@azure/msal-node": "^5.3.1",
+    "@azure/msal-node": "^5.4.0",
     "commander": "^15.0.0",
     "handlebars": "^4.7.9",
     "yaml": "^2.9.0",
     "zod": "^4.4.3"
   },
   "devDependencies": {
-    "tsdown": "^0.22.3"
+    "tsdown": "^0.22.4"
   }
 }