@novedu/cli 0.13.0 → 0.15.0

package/dist/main.js

@@ -442,6 +442,41 @@ function formatZodIssues(zodIssues) {
 	return out;
 }
 //#endregion
+//#region ../lib/prompt-fragments/text-files.ts
+/**
+* Split a body into logical lines for range slicing. `body.split("\n")` yields a
+* trailing empty element for a body that ends in a newline (`"a\n"` → `["a", ""]`); we
+* drop exactly ONE such trailing element so a conventional newline-terminated file
+* reports its real line count (`"a\n"` is one line, not two). An empty body is zero
+* lines. NB: this is ONLY for line-range math — a no-range `{{file}}` renders the body
+* byte-for-byte (see `load.ts`), trailing newline and all.
+*/
+function toLines(body) {
+	if (body === "") return [];
+	const lines = body.split("\n");
+	if (lines[lines.length - 1] === "") lines.pop();
+	return lines;
+}
+/** The number of logical lines in `body` (a newline-terminated final line is not double-counted). */
+function countLines(body) {
+	return toLines(body).length;
+}
+/**
+* Slice `body` to the 1-based inclusive line range `[from, to]` and re-join with `"\n"`,
+* appending nothing. `from` alone means "line `from` to end of file"; `to` alone means
+* "line 1 to `to`". `to` beyond EOF CLAMPS to end-of-file (native `Array.slice`
+* behaviour) — the runtime's graceful-degradation contract when a source file was
+* shortened after validation. The `from` lower bound is enforced by the caller
+* (`checkPlacements` errors on `from` beyond EOF), because an empty splice would
+* silently drop material.
+*/
+function sliceLines(body, from, to) {
+	const lines = toLines(body);
+	const start = from !== void 0 ? from - 1 : 0;
+	const end = to !== void 0 ? to : lines.length;
+	return lines.slice(start, end).join("\n");
+}
+//#endregion
 //#region ../lib/prompt-fragments/consistency.ts
 /** Compare a supplied value against its declared property type. Returns null when it matches. */
 function typeMismatch(prop, value) {
@@ -570,18 +605,33 @@ function mergeVariables(alias, fragment, args, errors, warnings) {
 	return merged;
 }
 /**
-* Cross-check every inline placement against the declared libraries: duplicate
-* aliases, duplicate fragment ids within a file, each placement's `alias.id`
-* resolution + variable validation (via `resolveAndMerge`), and a warning for any
-* declared library no placement ever uses. Errors block the build; the rest are
-* warnings. Order-independent — placements carry their own textual position.
+* Cross-check every inline placement against the declared libraries AND text files:
+* duplicate aliases (fragment libraries, text files, and collisions ACROSS the two —
+* one shared alias namespace), duplicate fragment ids within a file, each `{{fragment}}`
+* placement's `alias.id` resolution + variable validation (via `resolveAndMerge`), each
+* `{{file}}` placement's alias resolution + line-range bounds, and a warning for any
+* declared library / text file no placement ever uses. Errors block the build; the rest
+* are warnings. Order-independent — placements carry their own textual position.
+*
+* `textFilesByAlias` maps a declared text-file alias to its FETCHED body (needed for the
+* range bounds check); `strict` is the authoring-strictness flag — when set (authoring
+* validators / CLI), a `to` beyond EOF is an error too, whereas at runtime (`strict:
+* false`) the render layer clamps `to` to EOF instead. A `from` beyond EOF is ALWAYS an
+* error (an empty splice would silently drop material). The new params default so the
+* legacy fragment-only call sites (and their tests) need no change; the one real caller
+* (`load.ts`) always passes the text side explicitly.
 */
-function checkPlacements(placements, filesByAlias, fileRefs) {
+function checkPlacements(placements, filesByAlias, fileRefs, textFilesByAlias = /* @__PURE__ */ new Map(), textFileRefs = [], strict = false) {
 	const errors = [];
 	const warnings = [];
 	const aliasCounts = /* @__PURE__ */ new Map();
 	for (const ref of fileRefs) 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 fragmentAliases = new Set(fileRefs.map((r) => r.id));
+	const textAliasCounts = /* @__PURE__ */ new Map();
+	for (const ref of textFileRefs) textAliasCounts.set(ref.id, (textAliasCounts.get(ref.id) ?? 0) + 1);
+	for (const [alias, count] of textAliasCounts) if (count > 1) errors.push(error("DUPLICATE_TEXT_FILE_ALIAS", `Text-file alias "${alias}" is declared ${count} times`, { fileAlias: alias }));
+	else if (fragmentAliases.has(alias)) errors.push(error("DUPLICATE_TEXT_FILE_ALIAS", `Alias "${alias}" is declared as both a fragment library and a text file`, { fileAlias: alias }));
 	for (const [alias, file] of filesByAlias) {
 		const seen = /* @__PURE__ */ new Set();
 		for (const frag of file.fragments) {
@@ -596,18 +646,47 @@ function checkPlacements(placements, filesByAlias, fileRefs) {
 		}
 	}
 	const usedAliases = /* @__PURE__ */ new Set();
+	const usedTextAliases = /* @__PURE__ */ new Set();
 	for (const placement of placements) {
+		if (placement.kind === "file") {
+			checkFilePlacement(placement, textFilesByAlias, strict, errors);
+			usedTextAliases.add(placement.ref);
+			continue;
+		}
 		usedAliases.add(splitFragmentRef(placement.ref).alias);
 		const resolved = resolveAndMerge(placement.ref, placement.args, filesByAlias);
 		errors.push(...resolved.errors);
 		warnings.push(...resolved.warnings);
 	}
 	for (const ref of fileRefs) if (!usedAliases.has(ref.id)) warnings.push(warning("UNUSED_FRAGMENT_FILE", `Fragment library "${ref.id}" is declared but no {{fragment}} marker uses it`, { fileAlias: ref.id }));
+	for (const ref of textFileRefs) if (!usedTextAliases.has(ref.id)) warnings.push(warning("UNUSED_TEXT_FILE", `Text file "${ref.id}" is declared but no {{file}} marker embeds it`, { fileAlias: ref.id }));
 	return {
 		errors,
 		warnings
 	};
 }
+/**
+* Validate one `{{file}}` placement: the alias must be a declared text file, and its
+* line range must fit. `from` beyond EOF is ALWAYS an error (an empty splice would
+* silently drop material); `to` beyond EOF is an error ONLY under `strict` (authoring) —
+* at runtime the render layer clamps `to` to EOF so a shortened source degrades gracefully.
+*/
+function checkFilePlacement(placement, textFilesByAlias, strict, errors) {
+	const body = textFilesByAlias.get(placement.ref);
+	if (body === void 0) {
+		errors.push(error("UNKNOWN_TEXT_FILE_ALIAS", `File marker "${placement.ref}" uses unknown text-file alias`, { fileAlias: placement.ref }));
+		return;
+	}
+	const lineCount = countLines(body);
+	if (placement.from !== void 0 && placement.from > lineCount) errors.push(error("TEXT_FILE_RANGE_OUT_OF_BOUNDS", `File "${placement.ref}" has ${lineCount} line(s), but from=${placement.from} is past the end`, {
+		fileAlias: placement.ref,
+		line: placement.line
+	}));
+	if (strict && placement.to !== void 0 && placement.to > lineCount) errors.push(error("TEXT_FILE_RANGE_OUT_OF_BOUNDS", `File "${placement.ref}" has ${lineCount} line(s), but to=${placement.to} is past the end`, {
+		fileAlias: placement.ref,
+		line: placement.line
+	}));
+}
 //#endregion
 //#region ../lib/prompt-fragments/fetcher.ts
 const DEFAULT_TIMEOUT_MS = 1e4;
@@ -755,6 +834,28 @@ const FragmentFileRefSchema = z.strictObject({
 	id: "fragmentFileRef",
 	description: "A reference to a fragment library by alias + URL."
 });
+/**
+* A plain-text file reference: an `id` alias + a `url`, mirroring `FragmentFileRefSchema`
+* exactly (same no-dot alias regex, same http(s)-or-relative `FragmentUrlRef`). Unlike a
+* fragment library, a text file is arbitrary content (markdown course material, a
+* sample-solution source file) fetched over HTTP(S) and spliced VERBATIM into the host
+* text by an inline `{{file "alias"}}` marker — there is nothing to select inside it, so
+* the alias carries no dot. Text-file and fragment-file aliases share ONE namespace (an
+* `id` may not collide across the two lists), so every marker alias resolves unambiguously.
+*/
+const TextFileRefSchema = z.strictObject({
+	id: z.string().regex(/^[^.]+$/, { message: "Alias must not contain a dot" }).meta({
+		pattern: "^[^.]+$",
+		description: "Local alias for this text file, used in `{{file \"alias\"}}`. Must not contain a dot."
+	}),
+	url: FragmentUrlRef.meta({
+		pattern: "^(https?://|(?![A-Za-z][A-Za-z0-9+.-]*:).+)$",
+		description: "HTTP(S) URL or relative path to the plain-text file."
+	})
+}).meta({
+	id: "textFileRef",
+	description: "A reference to a plain-text file (markdown / source) by alias + URL."
+});
 //#endregion
 //#region ../lib/prompt-fragments/fragment.ts
 /**
@@ -850,8 +951,10 @@ function checkFragmentFileValue(parsed, url) {
 //#region ../lib/prompt-fragments/host-template.ts
 const FRAGMENT_HELPER = "fragment";
 const ARRAY_HELPER = "array";
+const FILE_HELPER = "file";
 const isFragmentNode = (node) => node.path?.original === FRAGMENT_HELPER;
-/** A structural error stamped with the node's 1-based position. */
+const isFileNode = (node) => node.path?.original === FILE_HELPER;
+/** A structural `{{fragment}}` error stamped with the node's 1-based position. */
 function markerInvalid(loc, detail) {
 	return error("FRAGMENT_MARKER_INVALID", `${detail} (line ${loc.start.line})`, {
 		line: loc.start.line,
@@ -859,6 +962,18 @@ function markerInvalid(loc, detail) {
 	});
 }
 /**
+* A structural `{{file}}` error stamped with the node's 1-based position. Every
+* `{{file}}` violation collapses to this ONE code (there is deliberately no separate
+* not-literal variant, unlike `{{fragment}}`): a file marker either parses into a valid
+* `alias`/`from`/`to` shape or fails closed here.
+*/
+function fileMarkerInvalid(loc, detail) {
+	return error("TEXT_FILE_MARKER_INVALID", `${detail} (line ${loc.start.line})`, {
+		line: loc.start.line,
+		column: loc.start.column + 1
+	});
+}
+/**
 * Read a hash-pair value into a supported literal. The supported set IS the contract:
 * a string, a boolean, or an `(array "…" …)` of string literals. Anything else — a
 * number, a path reference, a nested `(fragment …)`, an array with a non-string
@@ -903,25 +1018,75 @@ function extractInlineMarker(node, out) {
 		args[pair.key] = read.value;
 	}
 	out.placements.push({
+		kind: "fragment",
 		ref: first.value,
 		args,
 		line: node.loc.start.line,
 		column: node.loc.start.column + 1
 	});
 }
-/** Reject a `fragment` helper used anywhere but a simple inline mustache. */
+/**
+* Extract one inline `{{file "alias" from=N to=M}}` mustache's alias + optional range.
+* Structural contract (all TEXT_FILE_MARKER_INVALID, recording no placement on failure):
+* the first positional must be a quoted string literal, there is exactly one positional,
+* hash keys are restricted to `from` / `to`, each value must be an integer NumberLiteral
+* >= 1, and when both are present `from <= to`. A `from`/`to` beyond the file's actual
+* line count is NOT checked here (that needs the fetched body — see `checkPlacements`).
+*/
+function extractFileMarker(node, out) {
+	const first = node.params?.[0];
+	if (first?.type !== "StringLiteral") {
+		out.errors.push(fileMarkerInvalid(node.loc, "A {{file}} marker needs a quoted \"alias\" reference"));
+		return;
+	}
+	if ((node.params?.length ?? 0) > 1) {
+		out.errors.push(fileMarkerInvalid(node.loc, "A {{file}} marker takes exactly one \"alias\" reference"));
+		return;
+	}
+	let from;
+	let to;
+	for (const pair of node.hash?.pairs ?? []) {
+		if (pair.key !== "from" && pair.key !== "to") {
+			out.errors.push(fileMarkerInvalid(node.loc, `A {{file}} marker accepts only from= / to=, not "${pair.key}"`));
+			return;
+		}
+		if (pair.value.type !== "NumberLiteral" || !Number.isInteger(pair.value.value) || pair.value.value < 1) {
+			out.errors.push(fileMarkerInvalid(node.loc, `"${pair.key}" must be an integer line number >= 1`));
+			return;
+		}
+		if (pair.key === "from") from = pair.value.value;
+		else to = pair.value.value;
+	}
+	if (from !== void 0 && to !== void 0 && from > to) {
+		out.errors.push(fileMarkerInvalid(node.loc, `"from" (${from}) must not be greater than "to" (${to})`));
+		return;
+	}
+	out.placements.push({
+		kind: "file",
+		ref: first.value,
+		args: {},
+		...from !== void 0 ? { from } : {},
+		...to !== void 0 ? { to } : {},
+		line: node.loc.start.line,
+		column: node.loc.start.column + 1
+	});
+}
+/** Reject a `fragment` / `file` helper used anywhere but a simple inline mustache. */
 function visitExpression(node, out) {
 	if (node.type !== "SubExpression") return;
 	const sub = node;
 	if (isFragmentNode(sub)) out.errors.push(markerInvalid(sub.loc, "{{fragment}} must be a standalone inline marker, not a subexpression"));
+	else if (isFileNode(sub)) out.errors.push(fileMarkerInvalid(sub.loc, "{{file}} must be a standalone inline marker, not a subexpression"));
 	for (const p of sub.params ?? []) visitExpression(p, out);
 	for (const pair of sub.hash?.pairs ?? []) visitExpression(pair.value, out);
 }
-/** Collect every `{{fragment}}` marker in a program body (recursing into blocks). */
+/** Collect every `{{fragment}}` / `{{file}}` marker in a program body (recursing into blocks). */
 function collectPlacements(program, out) {
 	for (const node of program.body) {
 		if (isFragmentNode(node)) if (node.type === "MustacheStatement") extractInlineMarker(node, out);
 		else out.errors.push(markerInvalid(node.loc, "{{fragment}} must be a simple inline marker, not a block {{#fragment}}…{{/fragment}}"));
+		else if (isFileNode(node)) if (node.type === "MustacheStatement") extractFileMarker(node, out);
+		else out.errors.push(fileMarkerInvalid(node.loc, "{{file}} must be a simple inline marker, not a block {{#file}}…{{/file}}"));
 		else {
 			for (const p of node.params ?? []) visitExpression(p, out);
 			for (const pair of node.hash?.pairs ?? []) visitExpression(pair.value, out);
@@ -935,8 +1100,9 @@ function collectPlacements(program, out) {
 * order, WITHOUT rendering. A whole-template syntax error (a malformed marker, an
 * unescaped literal `{{`) becomes a single `HOST_TEMPLATE_PARSE_ERROR`; its position
 * is regexed out of Handlebars' message (`Parse error on line N:` — the parser
-* carries no structured position fields). A well-formed marker whose reference is not
-* a quoted string literal becomes a per-marker `FRAGMENT_REF_NOT_LITERAL`.
+* carries no structured position fields). A well-formed `{{fragment}}` marker whose
+* reference is not a quoted string literal becomes a per-marker `FRAGMENT_REF_NOT_LITERAL`;
+* a structurally wrong `{{file}}` marker becomes a per-marker `TEXT_FILE_MARKER_INVALID`.
 */
 function parseHostPlacements(text) {
 	const result = {
@@ -955,8 +1121,8 @@ function parseHostPlacements(text) {
 	collectPlacements(program, result);
 	return result;
 }
-/** Build the isolated Handlebars instance carrying ONLY the `fragment` + `array` helpers. */
-function createHostInstance(resolver) {
+/** Build the isolated Handlebars instance carrying ONLY the `fragment` + `array` + `file` helpers. */
+function createHostInstance(resolver, fileResolver) {
 	const hb = Handlebars.create();
 	hb.registerHelper(FRAGMENT_HELPER, (...args) => {
 		const ref = args.length >= 2 ? args[0] : void 0;
@@ -967,17 +1133,28 @@ function createHostInstance(resolver) {
 	hb.registerHelper(ARRAY_HELPER, (...args) => {
 		return args.slice(0, -1);
 	});
+	hb.registerHelper(FILE_HELPER, (...args) => {
+		const alias = args.length >= 2 ? args[0] : void 0;
+		if (typeof alias !== "string") throw new Error("a {{file}} marker needs a quoted \"alias\" reference");
+		const options = args[args.length - 1];
+		return fileResolver(alias, options?.hash?.from, options?.hash?.to);
+	});
 	return hb;
 }
 /**
 * Compile + render the host text with the isolated instance under
 * `{ strict: true, noEscape: true }` — `strict` so any stray `{{…}}` that is not a
-* `fragment` / `array` marker fails closed instead of rendering empty; `noEscape` so
-* the prompt text (ASCII diagrams, quotes) passes through verbatim. Each placement is
-* replaced by its `resolver` result. May throw — the caller wraps it as ASSEMBLY_ERROR.
+* `fragment` / `array` / `file` marker fails closed instead of rendering empty; `noEscape`
+* so the prompt text (ASCII diagrams, quotes) passes through verbatim. Each `{{fragment}}`
+* placement is replaced by its `resolver` result, each `{{file}}` by its `fileResolver`
+* result. May throw — the caller wraps it as ASSEMBLY_ERROR. `fileResolver` defaults to a
+* thrower: a template with no `{{file}}` markers never invokes it, but one that does
+* without a resolver fails closed rather than rendering wrong.
 */
-function renderHostTemplate(text, resolver) {
-	return createHostInstance(resolver).compile(text, {
+function renderHostTemplate(text, resolver, fileResolver = () => {
+	throw new Error("a {{file}} marker was rendered without a file resolver");
+}) {
+	return createHostInstance(resolver, fileResolver).compile(text, {
 		strict: true,
 		noEscape: true
 	})({});
@@ -996,6 +1173,8 @@ function resolveRelativeUrl(ref, baseUrl) {
 }
 //#endregion
 //#region ../lib/prompt-fragments/load.ts
+/** The 200 KB (UTF-8 bytes) per-file cap on an embedded `text_files:` body — fail closed above it. */
+const MAX_TEXT_FILE_BYTES = 200 * 1024;
 /**
 * 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 activity URL — standard URL resolution
@@ -1085,19 +1264,22 @@ async function loadYaml(url, fetchImpl, opts = {}) {
 * → check → render pipeline. `hostText` IS the template: fragments appear only where
 * the author placed a marker; there is no ordering concept and no prepend fallback.
 *
-* TEMPLATE-SEMANTICS OPT-IN: an activity that declares no `fragment_files:` is NEVER
-* compiled — its host text returns byte-verbatim (protecting plain activities and the
-* authoring tutors whose prose contains sample markers as teaching content).
+* TEMPLATE-SEMANTICS OPT-IN: an activity that declares NEITHER `fragment_files:` NOR
+* `text_files:` is NEVER compiled — its host text returns byte-verbatim (protecting plain
+* activities and the authoring tutors whose prose contains sample markers as teaching
+* content). Text files are fetched in parallel with the fragment libraries; each is kept
+* as a RAW string (no YAML parse) and spliced verbatim at render — never re-compiled as
+* Handlebars, so a literal `{{` in course material can never execute.
 */
 async function assembleFragmentPrompt(block, baseUrl, fetchImpl, opts = {}, hostText = "") {
 	const warnings = [];
 	const allowedSchemes = opts.allowedSchemes ?? DEFAULT_ALLOWED_SCHEMES;
-	if (block.fragment_files.length === 0) return {
+	if (block.fragment_files.length === 0 && block.text_files.length === 0) return {
 		ok: true,
 		prompt: hostText,
 		warnings
 	};
-	const settled = await Promise.all(block.fragment_files.map(async (ref) => {
+	const fragmentSettledPromise = Promise.all(block.fragment_files.map(async (ref) => {
 		let fragmentUrl;
 		try {
 			fragmentUrl = resolveFragmentUrl(ref.url, baseUrl);
@@ -1142,14 +1324,57 @@ async function assembleFragmentPrompt(block, baseUrl, fetchImpl, opts = {}, host
 			url: fragmentUrl
 		};
 	}));
+	const textSettledPromise = Promise.all(block.text_files.map(async (ref) => {
+		let fileUrl;
+		try {
+			fileUrl = resolveFragmentUrl(ref.url, baseUrl);
+		} catch {
+			return {
+				alias: ref.id,
+				error: error("INVALID_URL", `Invalid text-file URL: ${ref.url}`, {
+					url: ref.url,
+					fileAlias: ref.id
+				})
+			};
+		}
+		const schemeError = schemeGate(fileUrl, allowedSchemes);
+		if (schemeError) return {
+			alias: ref.id,
+			error: {
+				...schemeError,
+				fileAlias: ref.id
+			}
+		};
+		const fetched = await fetchText(fileUrl, fetchImpl);
+		if (!fetched.ok) return {
+			alias: ref.id,
+			error: fetched.error
+		};
+		const byteLength = new TextEncoder().encode(fetched.text).length;
+		if (byteLength > MAX_TEXT_FILE_BYTES) return {
+			alias: ref.id,
+			error: error("TEXT_FILE_TOO_LARGE", `Text file "${ref.id}" is ${byteLength} bytes, over the ${MAX_TEXT_FILE_BYTES}-byte limit`, {
+				url: fileUrl,
+				fileAlias: ref.id
+			})
+		};
+		return {
+			alias: ref.id,
+			body: fetched.text
+		};
+	}));
+	const [fragmentSettled, textSettled] = await Promise.all([fragmentSettledPromise, textSettledPromise]);
 	const fragmentFilesByAlias = /* @__PURE__ */ new Map();
 	const fragmentUrlByAlias = /* @__PURE__ */ new Map();
+	const textFilesByAlias = /* @__PURE__ */ new Map();
 	const fileErrors = [];
-	for (const result of settled) if ("error" in result) fileErrors.push(result.error);
+	for (const result of fragmentSettled) if ("error" in result) fileErrors.push(result.error);
 	else {
 		fragmentFilesByAlias.set(result.alias, result.file);
 		fragmentUrlByAlias.set(result.alias, result.url);
 	}
+	for (const result of textSettled) if ("error" in result) fileErrors.push(result.error);
+	else textFilesByAlias.set(result.alias, result.body);
 	if (fileErrors.length > 0) return {
 		ok: false,
 		errors: fileErrors,
@@ -1170,7 +1395,7 @@ async function assembleFragmentPrompt(block, baseUrl, fetchImpl, opts = {}, host
 		errors: [...libraryErrors, ...parsed.errors],
 		warnings
 	};
-	const placementCheck = checkPlacements(parsed.placements, fragmentFilesByAlias, block.fragment_files);
+	const placementCheck = checkPlacements(parsed.placements, fragmentFilesByAlias, block.fragment_files, textFilesByAlias, block.text_files, opts.validateLibraries ?? false);
 	warnings.push(...placementCheck.warnings);
 	const preRenderErrors = [...libraryErrors, ...placementCheck.errors];
 	if (preRenderErrors.length > 0) return {
@@ -1185,6 +1410,11 @@ async function assembleFragmentPrompt(block, baseUrl, fetchImpl, opts = {}, host
 				const resolved = resolveAndMerge(ref, args, fragmentFilesByAlias);
 				if (resolved.content === null || resolved.errors.length > 0) throw new Error(`Fragment "${ref}" could not be resolved`);
 				return renderFragmentContent(resolved.content, resolved.variables);
+			}, (alias, from, to) => {
+				const body = textFilesByAlias.get(alias);
+				if (body === void 0) throw new Error(`Text file "${alias}" was not prefetched`);
+				if (from === void 0 && to === void 0) return body;
+				return sliceLines(body, from, to);
 			}),
 			warnings
 		};
@@ -1227,7 +1457,8 @@ const CodingYamlSchema = z.strictObject({
 		description: "The pinned model and provider that answer coding requests."
 	}),
 	fragment_files: z.array(FragmentFileRefSchema).default([]).meta({ description: "Optional fragment libraries this activity pulls shared prompt fragments from." }),
-	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. When any fragment_files are declared it is a Handlebars template: place fragments inline with {{fragment \"alias.id\" …}} markers (escape a literal {{ as \\{{)." })
+	text_files: z.array(TextFileRefSchema).default([]).meta({ description: "Optional plain-text files (markdown / source, e.g. a sample solution) embedded verbatim into instructions via {{file \"alias\"}} markers." }),
+	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. When any fragment_files or text_files are declared it is a Handlebars template: place fragments inline with {{fragment \"alias.id\" …}} and embed text files with {{file \"alias\"}} (optionally {{file \"alias\" from=10 to=40}} for a line range; escape a literal {{ as \\{{)." })
 });
 //#endregion
 //#region ../lib/coding-validate.ts
@@ -1266,7 +1497,10 @@ async function loadAndCheckCoding(url, fetchImpl, opts = {}) {
 	};
 	const checked = checkCodingParsed(valid.data);
 	if (!checked.ok) return checked;
-	const assembled = await assembleFragmentPrompt({ fragment_files: valid.data.fragment_files }, url, fetchImpl, {
+	const assembled = await assembleFragmentPrompt({
+		fragment_files: valid.data.fragment_files,
+		text_files: valid.data.text_files
+	}, url, fetchImpl, {
 		allowedSchemes: opts.allowedSchemes,
 		validateLibraries: opts.validateLibraries ?? true
 	}, valid.data.instructions);
@@ -1283,6 +1517,25 @@ async function loadAndCheckCoding(url, fetchImpl, opts = {}) {
 }
 //#endregion
 //#region ../lib/quiz-schema.ts
+/**
+* A live quiz include: alias + URL, mirroring `FragmentFileRefSchema` (same URL
+* contract). The alias prefixes every imported question id as `"<alias>/<id>"`, so
+* on top of the no-dot rule it may not contain a `/` either. Aliases live in their
+* OWN namespace (they never appear in `{{…}}` markers — only in question ids).
+*/
+const QuizFileRefSchema = z.strictObject({
+	id: z.string().regex(/^[^./]+$/, { message: "Alias must not contain a dot or a slash" }).meta({
+		pattern: "^[^./]+$",
+		description: "Local alias for this included quiz. Prefixes every imported question id as \"<alias>/<id>\", so it may not contain a dot or a slash."
+	}),
+	url: FragmentFileRefSchema.shape.url.meta({
+		pattern: "^(https?://|(?![A-Za-z][A-Za-z0-9+.-]*:).+)$",
+		description: "HTTP(S) URL or relative path to the included quiz file."
+	})
+}).meta({
+	id: "quizFileRef",
+	description: "A reference to another quiz file whose questions are included live."
+});
 /** An optional content image attached to a question (carries no secret). */
 const ImageRefSchema = z.strictObject({
 	hosted: z.boolean().optional().meta({
@@ -1325,6 +1578,8 @@ const QuizYamlSchema = z.strictObject({
 		default: true,
 		description: "Present questions in a random order per attempt. Set to false to keep the authored order."
 	}),
+	question_count: z.number().int().min(1).optional().meta({ description: "How many questions one attempt asks (default: every question exactly once). May exceed the pool size — then questions repeat (drill mode). With shuffle off, fewer than the pool means the first N in authored order." }),
+	quiz_files: z.array(QuizFileRefSchema).default([]).meta({ description: "Other quiz files whose questions are ALL included live into this quiz (a compound/final quiz). One level deep — an included quiz may not itself declare quiz_files." }),
 	llm: z.strictObject({
 		model: z.string().min(1).meta({ description: "The model that grades answers and drives the per-question discussion chat." }),
 		provider: providerSchema,
@@ -1341,8 +1596,9 @@ const QuizYamlSchema = z.strictObject({
 		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." }),
-	instructions: z.string().optional().meta({ description: "Optional quiz-level preamble prepended to BOTH the grader prompt and the discussion chat. When any fragment_files are declared, place fragments inline here with {{fragment \"alias.id\" …}} markers (escape a literal {{ as \\{{)." }),
-	questions: z.array(QuizQuestionSchema).min(1).meta({ description: "The quiz questions. Each is open-ended and graded by the LLM via its evaluation prompt." })
+	text_files: z.array(TextFileRefSchema).default([]).meta({ description: "Optional plain-text files (markdown / source) embedded verbatim into instructions via {{file \"alias\"}} markers." }),
+	instructions: z.string().optional().meta({ description: "Optional quiz-level preamble prepended to BOTH the grader prompt and the discussion chat. When any fragment_files or text_files are declared, place fragments inline with {{fragment \"alias.id\" …}} and embed text files with {{file \"alias\"}} (optionally {{file \"alias\" from=10 to=40}} for a line range; escape a literal {{ as \\{{)." }),
+	questions: z.array(QuizQuestionSchema).default([]).meta({ description: "The quiz questions. Each is open-ended and graded by the LLM via its evaluation prompt. May be omitted when quiz_files supplies the questions." })
 });
 //#endregion
 //#region ../lib/quiz-validate.ts
@@ -1362,12 +1618,39 @@ function findDuplicateQuestionIds(quiz) {
 	return errors;
 }
 /**
-* Check an already-schema-validated quiz: unique question ids → metadata. Split from
+* Own question ids containing `/` — reserved as the namespace delimiter for
+* questions imported via `quiz_files` (`"<alias>/<id>"`), so an own id can never
+* collide with (or masquerade as) an imported one.
+*/
+function findReservedSlashIds(quiz) {
+	return quiz.questions.filter((question) => question.id.includes("/")).map((question) => error("QUIZ_QUESTION_ID_RESERVED_SLASH", `Question id "${question.id}" contains "/" — reserved for questions imported via quiz_files`, { questionId: question.id }));
+}
+/** Include aliases declared on more than one `quiz_files` entry. */
+function findDuplicateIncludeAliases(quiz) {
+	const errors = [];
+	const seen = /* @__PURE__ */ new Set();
+	for (const ref of quiz.quiz_files) {
+		if (seen.has(ref.id)) {
+			errors.push(error("DUPLICATE_QUIZ_INCLUDE_ALIAS", `Included-quiz alias "${ref.id}" is declared more than once`, { fileAlias: ref.id }));
+			continue;
+		}
+		seen.add(ref.id);
+	}
+	return errors;
+}
+/**
+* Check an already-schema-validated quiz: unique question ids, no reserved `/` ids,
+* unique include aliases, and a non-empty (potential) pool → 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 checkQuizParsed(quiz) {
-	const errors = findDuplicateQuestionIds(quiz);
+	const errors = [
+		...findDuplicateQuestionIds(quiz),
+		...findReservedSlashIds(quiz),
+		...findDuplicateIncludeAliases(quiz)
+	];
+	if (quiz.questions.length === 0 && quiz.quiz_files.length === 0) errors.push(error("QUIZ_NO_QUESTIONS", "This quiz has no questions and no quiz_files includes"));
 	if (errors.length > 0) return {
 		ok: false,
 		errors,
@@ -1384,12 +1667,83 @@ function checkQuizParsed(quiz) {
 		warnings: []
 	};
 }
+/** Wrap an include's nested failures into ONE error carrying the alias + URL. */
+function includeUnreadable(alias, url, nested) {
+	return error("QUIZ_INCLUDE_UNREADABLE", `Included quiz "${alias}" is not usable: ${nested.map((e) => e.message).join("; ")}`, url === void 0 ? { fileAlias: alias } : {
+		fileAlias: alias,
+		url
+	});
+}
+/**
+* Deep-check ONE `quiz_files` include: resolve + fetch + parse + the FULL strict
+* quiz check (schema, consistency passes, its own fragment-block authoring gate),
+* plus the one-level rule (`QUIZ_INCLUDE_NESTED`). Every other failure is wrapped
+* as `QUIZ_INCLUDE_UNREADABLE` with the alias + resolved URL.
+*/
+async function checkInclude(ref, baseUrl, fetchImpl, opts) {
+	let includeUrl;
+	try {
+		includeUrl = resolveFragmentUrl(ref.url, baseUrl);
+	} catch {
+		return {
+			ok: false,
+			errors: [includeUnreadable(ref.id, void 0, [error("INVALID_URL", `Invalid include URL: ${ref.url}`)])],
+			warnings: []
+		};
+	}
+	const yaml = await loadYaml(includeUrl, fetchImpl, opts);
+	if (!yaml.ok) return {
+		ok: false,
+		errors: [includeUnreadable(ref.id, includeUrl, [yaml.error])],
+		warnings: []
+	};
+	const valid = validate(yaml.value, QuizYamlSchema, "QUIZ_SCHEMA_ERROR", includeUrl);
+	if (!valid.ok) return {
+		ok: false,
+		errors: [includeUnreadable(ref.id, includeUrl, [valid.error])],
+		warnings: []
+	};
+	if (valid.data.quiz_files.length > 0) return {
+		ok: false,
+		errors: [error("QUIZ_INCLUDE_NESTED", `Included quiz "${ref.id}" itself declares quiz_files — includes are one level deep`, {
+			fileAlias: ref.id,
+			url: includeUrl
+		})],
+		warnings: []
+	};
+	const checked = checkQuizParsed(valid.data);
+	if (!checked.ok) return {
+		ok: false,
+		errors: [includeUnreadable(ref.id, includeUrl, checked.errors)],
+		warnings: checked.warnings
+	};
+	const assembled = await assembleFragmentPrompt({
+		fragment_files: valid.data.fragment_files,
+		text_files: valid.data.text_files
+	}, includeUrl, fetchImpl, {
+		allowedSchemes: opts.allowedSchemes,
+		validateLibraries: opts.validateLibraries ?? true
+	}, valid.data.instructions ?? "");
+	if (!assembled.ok) return {
+		ok: false,
+		errors: [includeUnreadable(ref.id, includeUrl, assembled.errors)],
+		warnings: assembled.warnings
+	};
+	return {
+		ok: true,
+		questionCount: valid.data.questions.length,
+		warnings: assembled.warnings
+	};
+}
 /**
 * Validate a quiz FILE: scheme-gate + fetch + parse (shared `loadYaml`), the pure
-* `checkQuizValue`, then the document-level fragment block's authoring gate — fetch
+* `checkQuizValue`, 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.
+* assembly dry-run (the strict-Handlebars backstop) — and a DEEP check of every
+* `quiz_files` include. On success `questionCount` is the RESOLVED pool size
+* (own + imported), so the `/files` save UI and code-create metadata reflect the
+* real exam size. 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);
@@ -1406,7 +1760,10 @@ async function loadAndCheckQuiz(url, fetchImpl, opts = {}) {
 	};
 	const checked = checkQuizParsed(valid.data);
 	if (!checked.ok) return checked;
-	const assembled = await assembleFragmentPrompt({ fragment_files: valid.data.fragment_files }, url, fetchImpl, {
+	const assembled = await assembleFragmentPrompt({
+		fragment_files: valid.data.fragment_files,
+		text_files: valid.data.text_files
+	}, url, fetchImpl, {
 		allowedSchemes: opts.allowedSchemes,
 		validateLibraries: opts.validateLibraries ?? true
 	}, valid.data.instructions ?? "");
@@ -1416,8 +1773,22 @@ async function loadAndCheckQuiz(url, fetchImpl, opts = {}) {
 		errors: assembled.errors,
 		warnings
 	};
+	const includes = await Promise.all(valid.data.quiz_files.map((ref) => checkInclude(ref, url, fetchImpl, opts)));
+	const includeErrors = [];
+	let importedCount = 0;
+	for (const include of includes) {
+		warnings.push(...include.warnings);
+		if (include.ok) importedCount += include.questionCount;
+		else includeErrors.push(...include.errors);
+	}
+	if (includeErrors.length > 0) return {
+		ok: false,
+		errors: includeErrors,
+		warnings
+	};
 	return {
 		...checked,
+		questionCount: checked.questionCount + importedCount,
 		warnings
 	};
 }
@@ -1458,7 +1829,8 @@ const TutorSchema = z.strictObject({
 	}),
 	prompt: z.strictObject({
 		fragment_files: z.array(FragmentFileRefSchema).default([]).meta({ description: "Optional fragment libraries used by this tutor." }),
-		tutor_instructions: z.string().meta({ description: "The tutor's system prompt. When any fragment_files are declared this is a Handlebars template: place fragments inline with {{fragment \"alias.id\" key=\"v\"}} markers (escape a literal {{ as \\{{). For single-file tutors it is the whole prompt." })
+		text_files: z.array(TextFileRefSchema).default([]).meta({ description: "Optional plain-text files (markdown / source) embedded verbatim via {{file \"alias\"}} markers." }),
+		tutor_instructions: z.string().meta({ description: "The tutor's system prompt. When any fragment_files or text_files are declared this is a Handlebars template: place fragments inline with {{fragment \"alias.id\" key=\"v\"}} markers and embed text files with {{file \"alias\"}} (optionally {{file \"alias\" from=10 to=40}} for a line range; escape a literal {{ as \\{{). For single-file tutors it is the whole prompt." })
 	}).meta({
 		id: "prompt",
 		description: "The tutor system prompt: a host template with inline fragment markers."
@@ -1520,7 +1892,8 @@ const WritingYamlSchema = z.strictObject({
 		description: "The model and provider that back the writing coach."
 	}),
 	fragment_files: z.array(FragmentFileRefSchema).default([]).meta({ description: "Optional fragment libraries this activity pulls shared prompt fragments from." }),
-	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. When any fragment_files are declared it is a Handlebars template: place fragments inline with {{fragment \"alias.id\" …}} markers (escape a literal {{ as \\{{)." }),
+	text_files: z.array(TextFileRefSchema).default([]).meta({ description: "Optional plain-text files (markdown / source) embedded verbatim into instructions via {{file \"alias\"}} markers." }),
+	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. When any fragment_files or text_files are declared it is a Handlebars template: place fragments inline with {{fragment \"alias.id\" …}} and embed text files with {{file \"alias\"}} (optionally {{file \"alias\" from=10 to=40}} for a line range; escape a literal {{ as \\{{)." }),
 	placeholder: z.string().optional().meta({ description: "Optional starter text prefilled into the editor. Empty for a blank page." })
 });
 //#endregion
@@ -1563,7 +1936,10 @@ async function loadAndCheckWriting(url, fetchImpl, opts = {}) {
 	};
 	const checked = checkWritingParsed(valid.data);
 	if (!checked.ok) return checked;
-	const assembled = await assembleFragmentPrompt({ fragment_files: valid.data.fragment_files }, url, fetchImpl, {
+	const assembled = await assembleFragmentPrompt({
+		fragment_files: valid.data.fragment_files,
+		text_files: valid.data.text_files
+	}, url, fetchImpl, {
 		allowedSchemes: opts.allowedSchemes,
 		validateLibraries: opts.validateLibraries ?? true
 	}, valid.data.instructions);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@novedu/cli",
-  "version": "0.13.0",
+  "version": "0.15.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": {