@novedu/cli 0.17.0 → 0.18.0

package/README.md

@@ -87,6 +87,7 @@ codes create  --module <tutor|quiz|writing|coding> --file <url>
               [--start <iso>] [--end <iso>] [--note <text>]
               [--llm-provider <p> --llm-model <m>]
 codes list    [--search <q>] [--module <m>] [--all]
+codes sync    <registry-file> [--lock <path>] [--dry-run] [--json]
 files upload  <name> [--kind <tutor|fragment|quiz|writing|coding>]
               (--file <path> | reads stdin)
 files list    [--search <q>] [--all]
@@ -103,6 +104,8 @@ images list   [--search <q>] [--all]
   shareable `url`. `--start`/`--end` must be ISO 8601 **with an explicit
   offset or `Z`** (e.g. `2026-07-07T08:00:00Z`); the
   `--llm-provider`/`--llm-model` override pair is both-or-nothing.
+- `codes sync <registry-file>` mints codes for a whole **course** at once — see
+  [Many activities at once](#many-activities-at-once-codes-sync) below.
 - `files upload <name>` is an **upsert**: creating a new file requires
   `--kind`; an existing file's kind is frozen at create time (a contradicting
   `--kind` fails with 409). The YAML comes from `--file <path>` or stdin.
@@ -150,6 +153,87 @@ image:
   alt: Merge sort splitting an array
 ```
 
+## Many activities at once: `codes sync`
+
+A course with twenty quizzes should not be twenty `codes create` calls whose
+codes you paste into twenty files by hand. Instead, keep an **activity registry**
+next to the material: one hand-written YAML file listing every activity under a
+stable key, plus a **lock file** the CLI generates and you commit.
+
+```yaml
+# yaml-language-server: $schema=https://raw.githubusercontent.com/Teaching-HTL-Leonding/novedu-chat-mvp/refs/heads/main/activities/registry/registry-yaml.schema.json
+# ddp-activities.yaml — the registry (you write this)
+base-url: "https://raw.githubusercontent.com/acme/course/refs/heads/main/"
+
+activities:
+  quizzes:
+    welcome:
+      file: 0010-introduction/0010-welcome-quiz.yaml
+      note: "Creative Coding book: Welcome (0010)"
+    number-systems:
+      file: 0030-conditions/0050-number-systems-quiz.yaml
+      start: 2026-09-01T00:00:00+02:00
+      end: 2027-01-31T23:59:59+01:00
+  tutors:
+    sorting:
+      url: https://novedu.at/api/files/sorting-tutor
+```
+
+```bash
+npx @novedu/cli codes sync ddp-activities.yaml
+# ddp-activities.yaml: 3 entries
+#   reused    welcome         cu4afwoa23  https://novedu.at/cu4afwoa23
+#   minted    number-systems  hb34gpvahn  https://novedu.at/hb34gpvahn
+#   reused    sorting         nlc90ezf5z  https://novedu.at/nlc90ezf5z
+#
+# 2 reused, 1 minted, 0 failed
+# Lock file: ddp-activities.lock.yaml
+```
+
+```yaml
+# ddp-activities.lock.yaml — generated; commit it, do not edit it
+activity-codes:
+  number-systems: hb34gpvahn
+  sorting: nlc90ezf5z
+  welcome: cu4afwoa23
+```
+
+- **Groups decide the module:** `quizzes`, `tutors`, `writing`, `coding`. Each
+  entry gives either `file` (relative to `base-url`, which must end in `/`) or
+  an absolute `url`, plus any of `start`/`end` (ISO 8601 **with an offset or
+  `Z`**, whole seconds), `note`, and an `llm: {provider, model}` override.
+- **Keys are yours and must be unique across all groups** — lowercase letters,
+  digits and hyphens. Your material references the key; the lock file maps it to
+  the code.
+- **Re-runs are safe.** An entry whose activity, window and model override match
+  an existing code of yours **reuses** that code; only entries without a match
+  are minted. So `codes sync` after every edit is the normal workflow, and the
+  first run against already-minted codes should report all-reused.
+- **Changing a window or override mints a NEW code.** The old one is not touched
+  (it keeps working) and is reported as superseded — delete it in the web app
+  when the class has moved on. Changing only the `note` never forks a code.
+- `--dry-run` shows what would happen without minting or writing anything;
+  `--json` prints the machine-readable report; `--lock <path>` puts the lock file
+  somewhere else.
+- One broken activity does not stop the run: it is reported as `failed`, the
+  other entries still sync, the lock keeps that entry's previous code, and the
+  command exits 1.
+- **A key keeps its code.** Two keys may point at the same activity on purpose
+  (one quiz linked from two chapters, each with its own statistics); they get one
+  code each, and neither moves on a later run.
+- Unknown extra keys are ignored, so you can annotate entries freely — but an
+  entry with nothing under it is an error, not an annotation, because that is
+  what a mis-indented entry looks like.
+- The `# yaml-language-server:` line on top is optional: it gives editors with
+  YAML support field completion, hover help and a warning on a misspelled group
+  name. `codes sync` is still the authority — it checks things a schema cannot,
+  such as key uniqueness and whether `end` is after `start`.
+
+Publications read the lock file offline. In a Quarto book, for example, add
+`metadata-files: [ddp-activities.lock.yaml]` to `_quarto.yml` and let the
+shortcode look the key up in `activity-codes` — the book then renders without
+ever calling the app.
+
 ## Triaging student reports (teacher account required)
 
 Students can flag an AI interaction — a chat or a graded quiz answer — with a

package/dist/main.js

@@ -1,16 +1,16 @@
 #!/usr/bin/env node
 import { mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { Command } from "commander";
+import { readFile, writeFile } from "node:fs/promises";
+import { basename, dirname, join, resolve } from "node:path";
 import { spawn } from "node:child_process";
 import { createServer } from "node:http";
 import { homedir } from "node:os";
-import { dirname, join, resolve } from "node:path";
 import { CryptoProvider, PublicClientApplication } from "@azure/msal-node";
-import { readFile } from "node:fs/promises";
+import { parse, stringify } from "yaml";
+import { z } from "zod";
 import { fileURLToPath, pathToFileURL } from "node:url";
 import Handlebars from "handlebars";
-import { parse } from "yaml";
-import { z } from "zod";
 //#region src/auth.ts
 const DEFAULT_TENANT_ID = "91fc072c-edef-4f97-bdc5-cfb67718ae3a";
 const DEFAULT_CLIENT_ID = "4d44fc4b-0434-4981-9765-62e2074ceecb";
@@ -174,8 +174,16 @@ async function acquireByDeviceCode(pca, onMessage) {
 * The one call every API command makes: a silently-acquired access token for
 * the Authorization header. Throws NotSignedInError when interactive login is
 * required first.
+*
+* `NOVEDU_TOKEN` short-circuits the MSAL cache with a caller-supplied bearer
+* token. It exists for TESTS and CI (the CLI integration suite runs the real
+* binary against a fake API, with no browser to sign in) — the token is still
+* validated by the server on every request, so this weakens nothing; it only
+* removes the interactive step. Not a substitute for `login` in normal use.
 */
 async function getAccessToken() {
+	const override = process.env.NOVEDU_TOKEN?.trim();
+	if (override) return override;
 	const result = await acquireSilent(buildPca());
 	if (!result) throw new NotSignedInError();
 	return result.accessToken;
@@ -206,20 +214,30 @@ function failJson(value) {
 * network, non-2xx) it prints the JSON error to stderr per the contract —
 * server error bodies (`{ message }` — incl. the generic 401/403 — or
 * `{ errors }`) passed through VERBATIM — marks the process failed, and
-* returns `{ ok: false }`. On success it returns the parsed payload WITHOUT
-* printing, so multi-step commands (`images upload`) can consume intermediate
-* responses silently. No client-side pre-validation: the server runs the
-* identical pipeline; offline checking is the `validate` command's job.
+* returns `{ ok: false, error }` with that same payload. On success it returns
+* the parsed payload WITHOUT printing, so multi-step commands (`images upload`)
+* can consume intermediate responses silently. No client-side pre-validation:
+* the server runs the identical pipeline; offline checking is the `validate`
+* command's job.
+*
+* `quiet` suppresses both the stderr print and the exit-code marking and hands
+* the failure payload back instead — for commands that make MANY requests and
+* report the outcome themselves (`codes sync`, where one entry's rejection must
+* not abort the run).
 */
 async function performApiRequest(options) {
+	const fail = (value) => {
+		if (!options.quiet) failJson(value);
+		return {
+			ok: false,
+			error: value
+		};
+	};
 	let token;
 	try {
 		token = await getAccessToken();
 	} catch (error) {
-		if (error instanceof NotSignedInError) {
-			failJson({ message: error.message });
-			return { ok: false };
-		}
+		if (error instanceof NotSignedInError) return fail({ message: error.message });
 		throw error;
 	}
 	const server = resolveServerUrl(options.server);
@@ -234,8 +252,7 @@ async function performApiRequest(options) {
 			body: options.body === void 0 ? void 0 : JSON.stringify(options.body)
 		});
 	} catch (error) {
-		failJson({ message: `Could not reach ${server}: ${error instanceof Error ? error.message : error}` });
-		return { ok: false };
+		return fail({ message: `Could not reach ${server}: ${error instanceof Error ? error.message : error}` });
 	}
 	let payload;
 	try {
@@ -243,10 +260,7 @@ async function performApiRequest(options) {
 	} catch {
 		payload = void 0;
 	}
-	if (!response.ok) {
-		failJson(payload ?? { message: `${server} rejected the request: HTTP ${response.status}` });
-		return { ok: false };
-	}
+	if (!response.ok) return fail(payload ?? { message: `${server} rejected the request: HTTP ${response.status}` });
 	return {
 		ok: true,
 		payload
@@ -262,8 +276,566 @@ async function runApiRequest(options) {
 	if (result.ok) printJson(result.payload ?? null);
 }
 //#endregion
+//#region ../lib/llm/provider.ts
+const LLM_PROVIDERS = ["SCCH", "Azure Foundry"];
+const providerSchema = z.enum(LLM_PROVIDERS).default("SCCH").meta({ description: "The LLM provider serving the model. For Azure Foundry, model is the deployment name." });
+//#endregion
+//#region ../lib/registry-schema.ts
+/** The fixed group names and the code module each one mints for. */
+const GROUP_MODULES = {
+	quizzes: "quiz",
+	tutors: "tutor",
+	writing: "writing",
+	coding: "coding"
+};
+const GROUP_NAMES = Object.keys(GROUP_MODULES);
+/** Registry keys share the lock file's flat namespace, so they stay URL/YAML-plain. */
+const KEY_PATTERN = /^[a-z0-9][a-z0-9-]*$/;
+const EXPLICIT_OFFSET = /(?:Z|[+-]\d{2}:?\d{2})$/;
+function timestampField(field) {
+	return z.string().refine((value) => EXPLICIT_OFFSET.test(value) && !Number.isNaN(Date.parse(value)), `${field} must be an ISO 8601 datetime with an explicit offset or Z, e.g. 2026-09-01T08:00:00+02:00`).refine((value) => {
+		const parsed = Date.parse(value);
+		return Number.isNaN(parsed) || parsed % 1e3 === 0;
+	}, `${field} must not carry sub-second precision — the server stores whole seconds`);
+}
+const providerField = z.enum(LLM_PROVIDERS, { error: "must be \"SCCH\" or \"Azure Foundry\"" });
+/**
+* One registry entry. Unknown extra properties are ACCEPTED and ignored so authors can
+* annotate freely and a newer registry keeps working with an older CLI — which is why
+* this is a `looseObject` and the generated JSON Schema does NOT flag a misspelled field.
+*/
+const RegistryEntrySchema = z.looseObject({
+	file: z.string().trim().min(1).optional().meta({ description: "Path to the activity YAML, resolved against `base-url`. Give exactly one of `file` or `url`." }),
+	url: z.string().trim().min(1).optional().meta({ description: "Absolute http(s) URL of the activity YAML. Give exactly one of `file` or `url`." }),
+	start: timestampField("start").optional().meta({ description: "Start of the code's validity window, ISO 8601 with an explicit offset or Z (e.g. 2026-09-01T08:00:00+02:00), whole seconds." }),
+	end: timestampField("end").optional().meta({ description: "End of the code's validity window, same format as `start`, and must be after it." }),
+	note: z.string().trim().max(200, `note must be at most 200 characters`).optional().meta({ description: `Note shown in the codes list, at most 200 characters. No effect on behaviour.` }),
+	llm: z.looseObject({
+		provider: providerField.meta({ description: "LLM provider override for this code. Required when `llm` is present." }),
+		model: z.string().trim().min(1).max(256).meta({ description: "Model id (for Azure Foundry, the deployment name). Required when `llm` is present." })
+	}).optional().meta({ description: "Per-code LLM override replacing the activity YAML's own `llm:`. Provider and model must be given together." })
+}).refine((entry) => entry.file === void 0 !== (entry.url === void 0), "give exactly one of `file` (relative to base-url) or `url` (absolute)").meta({
+	id: "registryEntry",
+	description: "One activity: where its YAML lives, plus the parameters its code is minted with."
+});
+/** A group holds `key: entry` pairs; an empty group (`quizzes:` with nothing under it) is fine. */
+function groupOf(group) {
+	return z.record(z.string().regex(KEY_PATTERN).max(64), RegistryEntrySchema).nullable().optional().meta({ description: `Activities minted as \`${GROUP_MODULES[group]}\` codes, keyed by the name your material references.` });
+}
+z.looseObject({
+	"base-url": z.string().optional().meta({ description: "Base URL each entry's `file` is resolved against. Must end with a slash. Only needed when an entry uses `file`." }),
+	activities: z.strictObject(Object.fromEntries(GROUP_NAMES.map((group) => [group, groupOf(group)]))).meta({ description: "The activities, grouped by the kind of code each one is minted as." })
+});
+//#endregion
+//#region src/registry.ts
+const rootSchema = z.looseObject({
+	"base-url": z.string().optional(),
+	activities: z.record(z.string(), z.unknown(), { error: "activities must be a mapping of activity groups" })
+});
+function issue(code, path, message) {
+	return {
+		code,
+		path,
+		message
+	};
+}
+/** Turns zod's issue list into registry issues rooted at `basePath`. */
+function schemaIssues(error, basePath) {
+	return error.issues.map((item) => issue("REGISTRY_SCHEMA_ERROR", [basePath, ...item.path.map(String)].filter(Boolean).join("."), item.message));
+}
+/** A plain YAML mapping — the shape both a group and an entry must have. */
+function isMapping(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/**
+* Parses and validates a registry document, resolving every entry's file URL.
+* Returns ALL issues found rather than the first — a registry is edited by hand,
+* so one run should surface every problem.
+*/
+function parseRegistry(text) {
+	let document;
+	try {
+		document = parse(text);
+	} catch (error) {
+		return {
+			ok: false,
+			errors: [issue("REGISTRY_PARSE_ERROR", "", `Invalid YAML: ${error instanceof Error ? error.message : String(error)}`)]
+		};
+	}
+	const root = rootSchema.safeParse(document ?? {});
+	if (!root.success) return {
+		ok: false,
+		errors: schemaIssues(root.error, "")
+	};
+	const errors = [];
+	const entries = [];
+	const seenKeys = /* @__PURE__ */ new Map();
+	const baseUrlText = root.data["base-url"];
+	let baseUrl;
+	if (baseUrlText !== void 0) {
+		const parsed = safeHttpUrl(baseUrlText);
+		if (!parsed) errors.push(issue("REGISTRY_SCHEMA_ERROR", "base-url", "must be an http(s) URL"));
+		else if (!parsed.endsWith("/")) errors.push(issue("REGISTRY_SCHEMA_ERROR", "base-url", "must end with a slash — it is resolved against, not concatenated with, each entry's `file`"));
+		else baseUrl = parsed;
+	}
+	for (const [groupName, groupValue] of Object.entries(root.data.activities)) {
+		const groupPath = `activities.${groupName}`;
+		if (!(groupName in GROUP_MODULES)) {
+			errors.push(issue("REGISTRY_SCHEMA_ERROR", groupPath, `unknown activity group — use one of ${GROUP_NAMES.join(", ")}`));
+			continue;
+		}
+		if (groupValue === null || groupValue === void 0) continue;
+		if (!isMapping(groupValue)) {
+			errors.push(issue("REGISTRY_SCHEMA_ERROR", groupPath, "must be a mapping of key → entry"));
+			continue;
+		}
+		const module = GROUP_MODULES[groupName];
+		for (const [key, value] of Object.entries(groupValue)) {
+			if (value !== null && !isMapping(value)) continue;
+			const entryPath = `${groupPath}.${key}`;
+			if (value === null) {
+				errors.push(issue("REGISTRY_SCHEMA_ERROR", entryPath, "entry has no fields — check the indentation of the lines below it"));
+				continue;
+			}
+			if (!KEY_PATTERN.test(key) || key.length > 64) {
+				errors.push(issue("REGISTRY_SCHEMA_ERROR", entryPath, `invalid key — use lowercase letters, digits and hyphens (max 64 characters)`));
+				continue;
+			}
+			const previousGroup = seenKeys.get(key);
+			if (previousGroup) {
+				errors.push(issue("REGISTRY_SCHEMA_ERROR", entryPath, `duplicate key — already defined under activities.${previousGroup}; keys are unique across all groups`));
+				continue;
+			}
+			seenKeys.set(key, groupName);
+			const parsed = RegistryEntrySchema.safeParse(value);
+			if (!parsed.success) {
+				errors.push(...schemaIssues(parsed.error, entryPath));
+				continue;
+			}
+			const entry = parsed.data;
+			if (entry.start && entry.end && Date.parse(entry.end) <= Date.parse(entry.start)) {
+				errors.push(issue("REGISTRY_SCHEMA_ERROR", `${entryPath}.end`, "must be after `start`"));
+				continue;
+			}
+			let fileUrl;
+			if (entry.url !== void 0) {
+				fileUrl = safeHttpUrl(entry.url);
+				if (!fileUrl) {
+					errors.push(issue("REGISTRY_SCHEMA_ERROR", `${entryPath}.url`, "must be an absolute http(s) URL"));
+					continue;
+				}
+			} else if (baseUrl === void 0) {
+				errors.push(issue("REGISTRY_SCHEMA_ERROR", `${entryPath}.file`, baseUrlText === void 0 ? "`file` is relative, but the registry has no `base-url`" : "`file` cannot be resolved — fix `base-url`"));
+				continue;
+			} else {
+				fileUrl = safeHttpUrl(entry.file ?? "", baseUrl);
+				if (!fileUrl) {
+					errors.push(issue("REGISTRY_SCHEMA_ERROR", `${entryPath}.file`, "does not resolve to an http(s) URL against `base-url`"));
+					continue;
+				}
+			}
+			entries.push({
+				key,
+				module,
+				fileUrl,
+				validFrom: entry.start ?? null,
+				validUntil: entry.end ?? null,
+				note: entry.note ?? null,
+				llm: entry.llm ? {
+					provider: entry.llm.provider,
+					model: entry.llm.model
+				} : null
+			});
+		}
+	}
+	return errors.length > 0 ? {
+		ok: false,
+		errors
+	} : {
+		ok: true,
+		entries
+	};
+}
+/**
+* Normalizes a (possibly relative) URL the way `validateCodeRequest` does —
+* `URL.href` — so a resolved entry compares byte-identical to the `file_url` the
+* server stored. Returns undefined for anything that is not http(s).
+*/
+function safeHttpUrl(value, base) {
+	let url;
+	try {
+		url = new URL(value.trim(), base);
+	} catch {
+		return;
+	}
+	return url.protocol === "http:" || url.protocol === "https:" ? url.href : void 0;
+}
+/** Reads and validates a registry file; a read failure is reported like a schema issue. */
+async function loadRegistry(path) {
+	let text;
+	try {
+		text = await readFile(path, "utf8");
+	} catch (error) {
+		return {
+			ok: false,
+			errors: [issue("REGISTRY_READ_ERROR", "", `Could not read ${path}: ${error instanceof Error ? error.message : String(error)}`)]
+		};
+	}
+	return parseRegistry(text);
+}
+/** The lock file that belongs to a registry: `<name>.yaml` → `<name>.lock.yaml`. */
+function defaultLockPath(registryPath) {
+	return `${registryPath.replace(/\.ya?ml$/i, "")}.lock.yaml`;
+}
+//#endregion
+//#region src/sync.ts
+/**
+* Narrows the `GET /api/codes` payload to the fields matching needs, dropping
+* anything unrecognizable. The CLI never fails on an unexpected extra field —
+* the server may grow the shape at any time.
+*/
+function parseServerCodes(payload) {
+	if (!Array.isArray(payload)) return [];
+	const codes = [];
+	for (const row of payload) {
+		if (typeof row !== "object" || row === null) continue;
+		const value = row;
+		if (typeof value.code !== "string" || typeof value.fileUrl !== "string") continue;
+		if (typeof value.module !== "string") continue;
+		const llm = value.llm;
+		codes.push({
+			code: value.code,
+			url: typeof value.url === "string" ? value.url : null,
+			module: value.module,
+			fileUrl: value.fileUrl,
+			note: typeof value.note === "string" ? value.note : null,
+			validFrom: typeof value.validFrom === "string" ? value.validFrom : null,
+			validUntil: typeof value.validUntil === "string" ? value.validUntil : null,
+			llm: typeof llm === "object" && llm !== null ? {
+				provider: String(llm.provider ?? ""),
+				model: String(llm.model ?? "")
+			} : null,
+			createdAt: typeof value.createdAt === "string" ? value.createdAt : null
+		});
+	}
+	return codes;
+}
+/**
+* Window bounds compare as INSTANTS, not as strings: the registry may spell a
+* moment `+02:00` while the server always answers in `Z`. An absent bound (null)
+* only matches an absent one.
+*/
+function sameInstant(a, b) {
+	if (a === null || b === null) return a === b;
+	const left = Date.parse(a);
+	const right = Date.parse(b);
+	return !Number.isNaN(left) && left === right;
+}
+function sameLlm(a, b) {
+	if (a === null || b === null) return a === b;
+	return a.provider === b.provider && a.model === b.model;
+}
+/**
+* The codes that ARE this entry: same activity URL, module and availability
+* window, same LLM override. `note` is deliberately excluded — it is a label for
+* the teacher, not part of the code's behavior, so editing it must not fork a
+* new code. Newest first, so the caller reuses the most recent one.
+*/
+function matchEntry(entry, codes) {
+	return codes.filter((code) => code.fileUrl === entry.fileUrl && code.module === entry.module && sameInstant(code.validFrom, entry.validFrom) && sameInstant(code.validUntil, entry.validUntil) && sameLlm(entry.llm, code.llm)).sort((a, b) => Date.parse(b.createdAt ?? "") - Date.parse(a.createdAt ?? "") || 0);
+}
+/**
+* Picks ONE code per registry key out of the pool, so a key's code never moves
+* while a matching code exists.
+*
+* Two entries may legitimately describe the same activity with the same window —
+* one quiz linked from two chapters, each wanting its own statistics — and both
+* then match both of the codes that minted for them. Taking "the newest match"
+* per entry independently would hand BOTH keys the same code, strand the other,
+* and flip the assignment whenever a newer code appeared: a key's published code
+* would move under the students already using it, and two consecutive runs of an
+* unchanged registry would write different lock files. Selection therefore
+* claims: every key that still matches the code it already has keeps it (all of
+* them, before any key takes a free one), then each remaining key takes the
+* newest code nobody has claimed.
+*/
+function selectMatches(entries, codes, previousLock) {
+	const candidates = /* @__PURE__ */ new Map();
+	for (const entry of entries) candidates.set(entry.key, matchEntry(entry, codes));
+	const selected = /* @__PURE__ */ new Map();
+	const claimed = /* @__PURE__ */ new Set();
+	for (const entry of entries) {
+		const previous = previousLock[entry.key];
+		if (!previous || claimed.has(previous)) continue;
+		const kept = candidates.get(entry.key)?.find((code) => code.code === previous);
+		if (!kept) continue;
+		selected.set(entry.key, kept);
+		claimed.add(kept.code);
+	}
+	for (const entry of entries) {
+		if (selected.has(entry.key)) continue;
+		const free = candidates.get(entry.key)?.find((code) => !claimed.has(code.code));
+		if (!free) continue;
+		selected.set(entry.key, free);
+		claimed.add(free.code);
+	}
+	return selected;
+}
+/** The mint body for an entry — exactly what `POST /api/codes` accepts. */
+function mintBody(entry) {
+	return {
+		module: entry.module,
+		fileUrl: entry.fileUrl,
+		...entry.validFrom === null ? {} : { validFrom: entry.validFrom },
+		...entry.validUntil === null ? {} : { validUntil: entry.validUntil },
+		...entry.note === null ? {} : { note: entry.note },
+		...entry.llm === null ? {} : { llm: entry.llm }
+	};
+}
+/**
+* Advisory findings for one run: codes the registry no longer describes but that
+* still exist for one of its activities (a parameter change mints a NEW code —
+* the old one is never touched), several codes matching one entry, and lock keys
+* that have left the registry. Nothing here is an error; superseded codes stay
+* live until a teacher deletes them in the web app.
+*/
+function collectWarnings(results, serverCodes, previousLock) {
+	const warnings = [];
+	const claimed = /* @__PURE__ */ new Set();
+	const inUse = new Set(results.filter((result) => result.action === "reused").map((result) => result.code));
+	for (const result of results) {
+		if (result.action !== "reused") continue;
+		const matches = matchEntry(result.entry, serverCodes);
+		for (const match of matches) claimed.add(match.code);
+		const spare = matches.filter((match) => match.code !== result.code && !inUse.has(match.code));
+		if (spare.length > 0) warnings.push({
+			type: "duplicate",
+			key: result.entry.key,
+			codes: matches.map((match) => match.code),
+			message: `${result.entry.key}: ${matches.length} codes match this entry — using ${result.code}; unused: ${spare.map((match) => match.code).join(", ")}`
+		});
+		const matched = matches.find((match) => match.code === result.code);
+		if (matched && (matched.note ?? "") !== (result.entry.note ?? "")) warnings.push({
+			type: "note",
+			key: result.entry.key,
+			codes: [matched.code],
+			message: `${result.entry.key}: the existing code's note differs from the registry's — a note is never re-applied to a minted code`
+		});
+	}
+	const activities = new Set(results.map((result) => `${result.entry.module} ${result.entry.fileUrl}`));
+	const superseded = serverCodes.filter((code) => !claimed.has(code.code) && activities.has(`${code.module} ${code.fileUrl}`));
+	for (const code of superseded) warnings.push({
+		type: "superseded",
+		codes: [code.code],
+		message: `${code.code}: an older code for ${code.fileUrl} no longer matches any registry entry — it still works; delete it in the web app when the class has moved on`
+	});
+	const keys = new Set(results.map((result) => result.entry.key));
+	for (const key of Object.keys(previousLock)) {
+		if (keys.has(key)) continue;
+		warnings.push({
+			type: "orphaned",
+			key,
+			codes: [previousLock[key] ?? ""],
+			message: `${key}: in the lock file but no longer in the registry — dropped from the lock; the code ${previousLock[key]} still exists`
+		});
+	}
+	return warnings;
+}
+/**
+* The lock content for a run. An entry that FAILED this run keeps the code the
+* previous lock had for it: a transient server error must never break the
+* consumer's build. A failed entry with no previous code is simply absent.
+*/
+function buildLockCodes(results, previousLock) {
+	const codes = {};
+	for (const result of results) {
+		const code = result.code ?? previousLock[result.entry.key];
+		if (code) codes[result.entry.key] = code;
+	}
+	return codes;
+}
+/** The single top-level key of a lock file — namespaced so it can be merged into other metadata. */
+const LOCK_ROOT_KEY = "activity-codes";
+/** Serializes the lock file: keys sorted, so a re-run produces a byte-identical file. */
+function serializeLock(codes, registryFileName) {
+	const sorted = {};
+	for (const key of Object.keys(codes).sort()) sorted[key] = codes[key];
+	return [
+		"# Generated by @novedu/cli — do not edit.",
+		`# Regenerate with: novedu-cli codes sync ${registryFileName}`,
+		stringify({ [LOCK_ROOT_KEY]: sorted })
+	].join("\n");
+}
+/** Reads a lock file's `activity-codes` map; anything unusable yields an empty map. */
+function parseLock(text) {
+	let document;
+	try {
+		document = parse(text);
+	} catch {
+		return {};
+	}
+	if (typeof document !== "object" || document === null) return {};
+	const map = document[LOCK_ROOT_KEY];
+	if (typeof map !== "object" || map === null) return {};
+	const codes = {};
+	for (const [key, value] of Object.entries(map)) if (typeof value === "string" && value) codes[key] = value;
+	return codes;
+}
+/**
+* The human-readable report: one line per entry (action, key, code, share URL or
+* the server's complaint), then the advisory findings, then a summary. Returned
+* as lines so the command decides where they go.
+*/
+function formatSyncReport(results, warnings, options) {
+	const width = Math.max(0, ...results.map((result) => result.entry.key.length));
+	const label = (action) => (options.dryRun && action === "minted" ? "would mint" : action).padEnd(9);
+	const lines = [`${options.registryFileName}: ${results.length} ${results.length === 1 ? "entry" : "entries"}`];
+	for (const result of results) {
+		const detail = result.action === "failed" ? describeError(result.error) : result.url ?? result.code ?? "(not minted — dry run)";
+		lines.push(`  ${label(result.action)} ${result.entry.key.padEnd(width)}  ${result.code ? `${result.code}  ` : ""}${detail}`);
+	}
+	if (warnings.length > 0) {
+		lines.push("", "Notes:");
+		for (const warning of warnings) lines.push(`  - ${warning.message}`);
+	}
+	const counts = {
+		reused: 0,
+		minted: 0,
+		failed: 0
+	};
+	for (const result of results) counts[result.action] += 1;
+	lines.push("", `${counts.reused} reused, ${counts.minted} ${options.dryRun ? "to mint" : "minted"}, ${counts.failed} failed`);
+	return lines;
+}
+/** A one-line rendering of the server's failure payload for the report. */
+function describeError(error) {
+	if (typeof error !== "object" || error === null) return String(error ?? "unknown error");
+	const value = error;
+	if (typeof value.message === "string") return value.message;
+	if (Array.isArray(value.errors)) return value.errors.map((item) => {
+		if (typeof item !== "object" || item === null) return String(item);
+		const detail = item;
+		return [detail.code, detail.message].filter(Boolean).join(": ");
+	}).join("; ");
+	return JSON.stringify(error);
+}
+//#endregion
 //#region src/commands/codes.ts
 const SERVER_OPTION$3 = ["--server <url>", "Novedu server base URL (defaults to the NOVEDU_SERVER env var, then production)"];
+/**
+* Reconciles a registry file with the server and rewrites its lock file: match
+* every entry against the caller's existing codes (URL + module + window + LLM
+* override), mint what has no match, and report the rest. Existing codes are
+* never modified or deleted — changed parameters produce a NEW code and the old
+* one is reported as superseded (docs/registry.md).
+*/
+async function runSync(registryFile, options) {
+	const registry = await loadRegistry(registryFile);
+	if (!registry.ok) {
+		failJson({
+			message: `${registryFile} is not a usable activity registry.`,
+			errors: registry.errors
+		});
+		return;
+	}
+	const lockPath = options.lock ?? defaultLockPath(registryFile);
+	const previousLock = await readLock(lockPath);
+	const listed = await performApiRequest({
+		server: options.server,
+		path: "/api/codes"
+	});
+	if (!listed.ok) return;
+	const serverCodes = parseServerCodes(listed.payload);
+	const results = [];
+	const selected = selectMatches(registry.entries, serverCodes, previousLock);
+	for (const entry of registry.entries) {
+		const match = selected.get(entry.key);
+		if (match) {
+			results.push({
+				entry,
+				action: "reused",
+				code: match.code,
+				url: match.url ?? void 0
+			});
+			continue;
+		}
+		if (options.dryRun) {
+			results.push({
+				entry,
+				action: "minted"
+			});
+			continue;
+		}
+		const created = await performApiRequest({
+			server: options.server,
+			path: "/api/codes",
+			method: "POST",
+			body: mintBody(entry),
+			quiet: true
+		});
+		if (!created.ok) {
+			results.push({
+				entry,
+				action: "failed",
+				error: created.error
+			});
+			continue;
+		}
+		const minted = created.payload;
+		if (typeof minted?.code !== "string" || minted.code === "") {
+			results.push({
+				entry,
+				action: "failed",
+				error: { message: "the server accepted the request but returned no code" }
+			});
+			continue;
+		}
+		results.push({
+			entry,
+			action: "minted",
+			code: minted.code,
+			url: typeof minted.url === "string" ? minted.url : void 0
+		});
+	}
+	const warnings = collectWarnings(results, serverCodes, previousLock);
+	const failed = results.filter((result) => result.action === "failed").length;
+	if (options.json) printJson({
+		...options.dryRun ? { dryRun: true } : {},
+		entries: results.map((result) => ({
+			key: result.entry.key,
+			module: result.entry.module,
+			fileUrl: result.entry.fileUrl,
+			action: result.action,
+			...result.code ? { code: result.code } : {},
+			...result.url ? { url: result.url } : {},
+			...result.action === "failed" ? { error: result.error } : {}
+		})),
+		warnings
+	});
+	else for (const line of formatSyncReport(results, warnings, {
+		registryFileName: basename(registryFile),
+		dryRun: Boolean(options.dryRun)
+	})) console.log(line);
+	if (!options.dryRun) {
+		const lock = serializeLock(buildLockCodes(results, previousLock), basename(registryFile));
+		try {
+			await writeFile(lockPath, lock, "utf8");
+		} catch (error) {
+			failJson({ message: `Could not write the lock file ${lockPath}: ${error instanceof Error ? error.message : error}` });
+			return;
+		}
+		if (!options.json) console.log(`Lock file: ${lockPath}`);
+	}
+	if (failed > 0) process.exitCode = 1;
+}
+/** The lock file's previous content; a missing or unreadable lock is simply empty. */
+async function readLock(lockPath) {
+	try {
+		return parseLock(await readFile(lockPath, "utf8"));
+	} catch {
+		return {};
+	}
+}
 function registerCodes(program) {
 	const codes = program.command("codes").description("Manage activity codes on the Novedu server");
 	codes.command("create").description("Create a code for an activity YAML (validated server-side before storing)").requiredOption("--module <module>", "activity module: tutor, quiz, writing or coding").requiredOption("--file <url>", "public http(s) URL of the activity YAML").option("--start <iso>", "window start, ISO 8601 with explicit offset (e.g. 2026-07-07T08:00:00Z)").option("--end <iso>", "window end, ISO 8601 with explicit offset").option("--note <text>", "note shown in the codes list").option("--llm-provider <provider>", "LLM override provider (\"SCCH\" or \"Azure Foundry\"; needs --llm-model)").option("--llm-model <model>", "LLM override model id (needs --llm-provider)").option(...SERVER_OPTION$3).action(async (options) => {
@@ -295,6 +867,9 @@ function registerCodes(program) {
 			path: `/api/codes${query ? `?${query}` : ""}`
 		});
 	});
+	codes.command("sync").description("Reconcile an activity registry file with the server and write its lock file").argument("<registry-file>", "path to the hand-written activity registry YAML").option("--lock <path>", "lock file path (default: the registry path with .lock.yaml)").option("--dry-run", "report what would happen; mint nothing and write no lock file").option("--json", "machine-readable report on stdout instead of the per-entry lines").option(...SERVER_OPTION$3).action(async (registryFile, options) => {
+		await runSync(registryFile, options);
+	});
 }
 //#endregion
 //#region src/commands/files.ts
@@ -1576,7 +2151,6 @@ async function loadAndCheckFragmentFile(url, fetchImpl, opts = {}) {
 	};
 	return checkFragmentFileValue(yaml.value, url);
 }
-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({

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@novedu/cli",
-  "version": "0.17.0",
+  "version": "0.18.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, app-hosted files and images over the app's API.",
   "type": "module",
   "repository": {