@master/css-mcp 2.1.1 → 2.1.3

package/README.md

@@ -1,6 +1,6 @@
 # Master CSS MCP Server
 
-Model Context Protocol server for Master CSS tooling. It lets AI clients inspect a Master CSS workspace, audit setup, read the active project manifest, inspect CSS-first directives, trace classes through extraction and generated CSS, render or compare CSS output, run lint diagnostics, request syntax suggestions, and apply reviewed fix previews.
+Model Context Protocol server for Master CSS tooling. It lets AI clients inspect a Master CSS workspace, audit setup, read the active project manifest, inspect CSS-first directives, trace classes through extraction and generated CSS, render or compare CSS output, run lint diagnostics, request syntax suggestions, read and check the component contracts of a design system, and apply reviewed fix previews.
 
 ## Installation
 
@@ -60,6 +60,9 @@ The `preset` context uses the bundled Master CSS defaults, so this check works b
 | `mastercss_lint_project` | Run class-list diagnostics for workspace files without writing files. |
 | `mastercss_lint_content` | Run class-list diagnostics on an in-memory source buffer without writing files. |
 | `mastercss_suggest_syntax` | Return language-service completions and hover context. |
+| `mastercss_contract_list` | List the component contracts of the workspace's design-system dependencies, merged with the project's own. Filter by `query`, `tier`, or `category`. |
+| `mastercss_contract_get` | Return one full contract and its source by contract name or by any class it defines. |
+| `mastercss_contract_check` | Check an in-memory source buffer or workspace files against the contracts with the checker a design-system dependency declares, without writing files. |
 | `mastercss_preview_fixes` | Create a diff preview and confirmation token. |
 | `mastercss_preview_directive_format` | Preview Master CSS directive formatting for files, or format in-memory content without writing. |
 | `mastercss_apply_preview` | Apply a preview after token, hash, and workspace checks. |
@@ -92,6 +95,51 @@ The report covers project-owned CSS reached from the project's Master CSS entrie
 
 Metadata and policies are analysis inputs: they do not change generated CSS, manifests, or runtime programs. Unrecognized option fields are rejected. Omit `rawValuePolicy` to skip native declaration raw-value checks. Read `project.excluded` and `coverage`: package sources and files outside the project root are excluded, importer links include reference-only context, and the report does not establish DOM usage, cascade winners, computed styles, or browser behavior. `includeSnapshot` remains available in the same call.
 
+## Contracts of a design system
+
+A design system built on Master CSS can describe each component in a contract: its classes and where they go, its states, public properties and smallest correct markup. The contract tools serve those contracts from the same server, so an agent can read a component's contract before writing its markup and check the result afterward. [`@master/ui`](https://ui.master.co) is the first library that ships contracts this way.
+
+A library declares its contracts in its own `package.json`:
+
+```json
+{
+  "name": "your-design-system",
+  "masterCSS": {
+    "contracts": "./dist/contracts.json",
+    "check": "./check/index.js"
+  }
+}
+```
+
+- `contracts` is a path inside the package to a JSON file holding `{ "contracts": [...] }`. A contract is an object with a string `name` and a `classes` array; every other field belongs to the library.
+- `check` is optional: a path inside the package to an ES module that exports `check(source, contracts, { knows, strict })` and returns diagnostics with `code`, `severity`, `message`, `line`, `column` and, when they apply, `className` and `contract`.
+
+The server reads `dependencies`, `devDependencies` and `peerDependencies` from the `package.json` in the workspace root, resolves each package from that root and keeps those that declare `masterCSS.contracts`. Packages that do not resolve or do not declare the field are skipped. When none declares contracts, the server reads the same fields of the monorepo root above: the nearest directory whose `package.json` lists `workspaces` or that holds a `pnpm-workspace.yaml`, without leaving the repository.
+
+A project adds contracts of its own with globs in the same field of its root `package.json`, one contract per JSON file:
+
+```json
+{
+  "masterCSS": {
+    "contracts": ["contracts/*.json"]
+  }
+}
+```
+
+A project with a `master-ui.json` also contributes the JSON files of its `directory` (`ui` by default) and its `contracts` globs. A project contract replaces a library contract of the same `name`. Every contract in a result carries its `source`: `{ "kind": "package", "package", "version" }`, or `{ "kind": "project", "file" }` with `replaces` naming the library contract it took over.
+
+| Call | Result |
+| --- | --- |
+| `mastercss_contract_list` with optional `query`, `tier`, `category` | `libraries` (name, version, contract count, whether it has a checker) and a compact `contracts` list. Nothing declaring contracts is an empty list with a `note`, not an error. |
+| `mastercss_contract_get` with `name` | The full `contract` and its `source`. `name` is a contract name or any class in a contract, so `btn-primary` returns the button contract. An unknown name is an error that lists the closest contract and class names. |
+| `mastercss_contract_check` with `content` and optional `filePath`, or `patterns` | Diagnostics per file, a `summary`, `coverage`, and the `checkers` that ran. Without input it checks the project's markup files. |
+
+A library in its own repository can declare `masterCSS.check` in the root `package.json` too; that checker then reads the contracts its root `masterCSS.contracts` globs select.
+
+`mastercss_contract_check` runs code from the package that declares the checker. The server imports it only from a path inside that package, runs it in a worker thread, and stops it with `CONTRACT_CHECKER_FAILED` when one file takes longer than 10 seconds or the checker exceeds its memory limit. Each check loads the checker again, so an upgraded library takes effect without a restart.
+
+`mastercss_contract_check` passes the checker `knows(className)`, which answers from the project manifest whether a class is a valid Master CSS class or a native class of the project's stylesheets, and `strict: true` only when that manifest loaded; `classValidation` and `strict` in the result say which happened. When contracts exist but no library declares a checker, `coverage.status` is `no-checker` and lookups still work. With several libraries, each checker reads its own library's contracts as the project replaced them, and contracts no checker owns go to the first one.
+
 ## Prompt templates
 
 | Prompt | Use |
@@ -106,7 +154,9 @@ Every tool returns a `version: 3` envelope with `metadata`, `diagnostics` and `r
 
 ## Safety
 
-Read-only tools do not write files. File writes use a two-step preview/apply flow, validate workspace containment, and verify original file hashes before writing. Lint fixes, generated CSS output writes, and directive formatting for files all use preview tokens before `mastercss_apply_preview` can write anything.
+Read-only tools do not write files. `mastercss_contract_check` is the one tool that runs code from the workspace: it imports the checker module of a package that is a declared dependency of the workspace root, only from a path inside that package, and runs it in the server process. Project contract files are read as data and never executed. Restart the server after upgrading a library so that its checker is loaded again.
+
+File writes use a two-step preview/apply flow, validate workspace containment, and verify original file hashes before writing. Lint fixes, generated CSS output writes, and directive formatting for files all use preview tokens before `mastercss_apply_preview` can write anything.
 
 Concurrent applies coordinate across MCP processes for the same OS user through a local lock directory under `~/.cache/mastercss`. Hash validation and writes run one apply at a time across all workspace roots. A waiting apply times out after 30 seconds without taking over a live writer; its token can be retried until it expires. External editors do not participate in this lock, so edits made after hash validation can still race with apply. Multi-file writes are sequential and do not provide rollback or crash atomicity.
 

package/dist/contract-schema.js

@@ -0,0 +1,104 @@
+import { metadata, strings } from "./semantic-schema.js";
+import * as z from "zod/v4";
+// src/contract-schema.ts
+const count = z.number().int().nonnegative();
+const owner = z.object({
+	package: z.string(),
+	version: z.string().nullable()
+});
+/** Where a contract comes from: the library that ships it, or the project file that defines or replaces it. */
+const contractSource = z.discriminatedUnion("kind", [owner.extend({ kind: z.literal("package") }), z.object({
+	kind: z.literal("project"),
+	file: z.string(),
+	replaces: owner.optional()
+})]);
+const library = z.object({
+	name: z.string(),
+	version: z.string().nullable(),
+	count,
+	checker: z.boolean()
+});
+const entry = z.object({
+	name: z.string(),
+	title: z.string().optional(),
+	tier: z.string().optional(),
+	category: z.string().optional(),
+	description: z.string().optional(),
+	use: z.string().optional(),
+	script: z.string().optional(),
+	source: contractSource
+});
+const contract = z.object({
+	name: z.string(),
+	classes: z.array(z.json())
+}).passthrough();
+const diagnostic = z.object({
+	code: z.string(),
+	severity: z.enum([
+		"error",
+		"warning",
+		"info"
+	]),
+	message: z.string(),
+	line: count,
+	column: count,
+	className: z.string().optional(),
+	contract: z.string().optional(),
+	source: z.string()
+});
+const contractList = {
+	version: z.literal(1),
+	root: z.string(),
+	libraries: z.array(library),
+	contracts: z.array(entry),
+	summary: z.object({
+		libraries: count,
+		contracts: count,
+		returned: count
+	}),
+	note: z.string().optional()
+};
+const contractGet = {
+	version: z.literal(1),
+	root: z.string(),
+	name: z.string(),
+	matched: z.enum(["contract", "class"]),
+	contract,
+	source: contractSource
+};
+const contractCheck = {
+	version: z.literal(1),
+	root: z.string(),
+	manifest: metadata.optional(),
+	libraries: z.array(library),
+	checkers: z.array(owner.extend({ contracts: count })),
+	classValidation: z.enum(["project-manifest", "none"]),
+	strict: z.boolean(),
+	files: z.array(z.object({
+		filePath: z.string(),
+		diagnostics: z.array(diagnostic)
+	})),
+	coverage: z.object({
+		status: z.enum([
+			"complete",
+			"no-inputs",
+			"no-checker",
+			"no-contracts"
+		]),
+		checkedFiles: strings,
+		skippedFiles: z.array(z.object({
+			filePath: z.string(),
+			reason: z.string()
+		})),
+		description: z.string()
+	}),
+	summary: z.object({
+		checkedFiles: count,
+		filesWithDiagnostics: count,
+		diagnostics: count,
+		errors: count,
+		warnings: count
+	}),
+	note: z.string().optional()
+};
+export { contractCheck, contractGet, contractList, contractSource };

package/dist/contracts.js

@@ -0,0 +1,623 @@
+import { getErrorMessage } from "./result.js";
+import { loadWorkspaceManifest, manifestMetadata } from "./project.js";
+import { createMCPToolingSession } from "./tooling-session.js";
+import { resolveSourceFiles } from "./scan.js";
+import { dirname, isAbsolute, join, relative, resolve } from "node:path";
+import { pathToFileURL } from "node:url";
+import { readFile, realpath, stat } from "node:fs/promises";
+import fg from "fast-glob";
+import { Worker } from "node:worker_threads";
+// src/contracts.ts
+/**
+* Contracts of a design system built on Master CSS.
+*
+* A package declares them in its package.json:
+*   "masterCSS": { "contracts": "./dist/contracts.json", "check": "./check/index.js" }
+* `contracts` names a JSON file holding `{ contracts: [...] }`; the optional `check` names an ES module
+* exporting `check(source, contracts, { knows, strict })`. A project adds or replaces contracts with its own
+* JSON files, and a library checking itself declares its `check` in the workspace's own package.json. This module
+* only reads that protocol: it knows no design system by name.
+*/
+const CONTRACT_REPORT_VERSION = 1;
+const MAX_CONTRACT_FILE_BYTES = 16777216;
+const MAX_PROJECT_CONTRACT_FILES = 2e3;
+const MAX_CHECK_FILES = 5e3;
+const MAX_CHECK_FILE_BYTES = 2097152;
+const MAX_DIAGNOSTICS_PER_FILE = 500;
+const MAX_CHECK_CONTENT_LENGTH = MAX_CHECK_FILE_BYTES;
+const DEFAULT_CHECK_PATTERNS = ["**/*.{html,htm,jsx,tsx,svelte,astro,vue,mdx,php}"];
+const DEFAULT_IGNORE_PATTERNS = ["**/node_modules/**", "node_modules"];
+const PACKAGE_NAME = /^(?:@[a-z0-9~-][a-z0-9._~-]*\/)?[a-z0-9~-][a-z0-9._~-]*$/i;
+const NO_CONTRACTS_NOTE = "No dependency of this workspace declares \"masterCSS.contracts\" in its package.json, and the project defines no contracts of its own.";
+const DEPENDENCY_FIELDS = [
+	"dependencies",
+	"devDependencies",
+	"peerDependencies"
+];
+/** Limits of one checker call, read at every check. A checker that exceeds them is stopped, not the server. */
+const contractCheckerLimits = {
+	timeoutMs: 1e4,
+	memoryMb: 512
+};
+const record = (value) => value && typeof value === "object" && !Array.isArray(value) ? value : {};
+const text = (value) => typeof value === "string" && value ? value : void 0;
+const strings = (value) => (Array.isArray(value) ? value : [value]).filter((item) => typeof item === "string" && item.length > 0);
+const posix = (path) => path.replaceAll("\\", "/");
+function inside(directory, filePath) {
+	const path = relative(directory, filePath);
+	return Boolean(path) && !path.startsWith("..") && !isAbsolute(path);
+}
+async function readJSON(filePath) {
+	try {
+		if ((await stat(filePath)).size > MAX_CONTRACT_FILE_BYTES) return {
+			error: `larger than ${MAX_CONTRACT_FILE_BYTES} bytes`,
+			missing: false
+		};
+		return { value: JSON.parse(await readFile(filePath, "utf8")) };
+	} catch (error) {
+		return {
+			error: getErrorMessage(error),
+			missing: record(error).code === "ENOENT"
+		};
+	}
+}
+/** A file inside a package directory, with links resolved so a path cannot leave the package. */
+async function resolveInside(directory, path) {
+	if (isAbsolute(path)) return void 0;
+	try {
+		const filePath = await realpath(resolve(directory, path));
+		return inside(directory, filePath) && (await stat(filePath)).isFile() ? filePath : void 0;
+	} catch {
+		return;
+	}
+}
+/** Where Node resolves a bare package name from the root, without requiring an exported package.json. */
+async function findPackageDirectory(root, name) {
+	for (let directory = root;; directory = dirname(directory)) {
+		const manifest = join(directory, "node_modules", name, "package.json");
+		if ((await stat(manifest).catch(() => void 0))?.isFile()) return realpath(dirname(manifest));
+		if (dirname(directory) === directory) return void 0;
+	}
+}
+const exists = (path) => stat(path).then(() => true, () => false);
+/** The nearest ancestor that roots a workspace, without leaving the repository that holds the root. */
+async function findWorkspaceRoot(root) {
+	if (await exists(join(root, ".git"))) return void 0;
+	for (let directory = dirname(root); directory !== dirname(directory); directory = dirname(directory)) {
+		const manifest = await readJSON(join(directory, "package.json"));
+		const pkg = record("value" in manifest ? manifest.value : void 0);
+		if (pkg.workspaces || await exists(join(directory, "pnpm-workspace.yaml"))) return {
+			directory,
+			pkg
+		};
+		if (await exists(join(directory, ".git"))) return void 0;
+	}
+}
+const isContract = (value) => typeof record(value).name === "string" && record(value).name !== "" && Array.isArray(record(value).classes);
+/** One contract, or the contracts of a `{ contracts: [...] }` file. Anything else holds none. */
+function contractsIn(value) {
+	if (isContract(value)) return [value];
+	const { contracts } = record(value);
+	return Array.isArray(contracts) ? contracts.filter(isContract) : [];
+}
+const classNamesOf = (contract) => contract.classes.flatMap((entry) => text(record(entry).name) ?? []);
+/** The libraries among the dependencies a package.json declares, resolved from its directory. */
+async function readLibraries(root, pkg, libraries, merged, warn) {
+	for (const dependency of new Set(DEPENDENCY_FIELDS.flatMap((field) => Object.keys(record(pkg[field]))))) {
+		if (!PACKAGE_NAME.test(dependency)) continue;
+		const directory = await findPackageDirectory(root, dependency);
+		if (!directory) continue;
+		const manifest = await readJSON(join(directory, "package.json"));
+		if (!("value" in manifest)) continue;
+		const pkg = record(manifest.value);
+		const declared = record(pkg.masterCSS);
+		const contractPaths = strings(declared.contracts);
+		if (!contractPaths.length) continue;
+		const owner = {
+			package: text(pkg.name) ?? dependency,
+			version: text(pkg.version) ?? null
+		};
+		if (libraries.some((library) => library.name === owner.package)) continue;
+		const library = {
+			name: owner.package,
+			version: owner.version,
+			count: 0
+		};
+		for (const path of contractPaths) {
+			const filePath = await resolveInside(directory, path);
+			const file = filePath ? await readJSON(filePath) : {
+				error: "not a file inside the package",
+				missing: true
+			};
+			if (!("value" in file)) {
+				warn("CONTRACT_FILE_UNREADABLE", `${owner.package} declares masterCSS.contracts "${path}", which could not be read: ${file.error}`);
+				continue;
+			}
+			for (const contract of contractsIn(file.value)) {
+				library.count++;
+				const existing = merged.get(contract.name);
+				if (existing) {
+					const other = existing.source.kind === "package" ? existing.source.package : existing.source.file;
+					if (other !== owner.package) warn("CONTRACT_NAME_COLLISION", `${owner.package} and ${other} both declare a contract named "${contract.name}"; ${other} is kept.`);
+					continue;
+				}
+				merged.set(contract.name, {
+					contract,
+					source: {
+						kind: "package",
+						...owner
+					},
+					library: owner.package
+				});
+			}
+		}
+		const check = text(declared.check);
+		if (check) {
+			library.checkPath = await resolveInside(directory, check);
+			if (!library.checkPath) warn("CONTRACT_CHECKER_UNRESOLVED", `${owner.package} declares masterCSS.check "${check}", which is not a file inside the package.`);
+		}
+		libraries.push(library);
+	}
+}
+/** Read every contract that applies to the workspace. Nothing here executes package or project code. */
+async function discoverContracts(context) {
+	const warnings = [];
+	const warn = (code, message) => {
+		warnings.push({
+			code,
+			phase: "contract-discovery",
+			severity: "warning",
+			message
+		});
+	};
+	const rootManifest = await readJSON(join(context.root, "package.json"));
+	if (!("value" in rootManifest) && !rootManifest.missing) warn("CONTRACT_PACKAGE_JSON_UNREADABLE", `The workspace package.json could not be read: ${rootManifest.error}`);
+	const rootPackage = record("value" in rootManifest ? rootManifest.value : void 0);
+	const libraries = [];
+	const merged = /* @__PURE__ */ new Map();
+	await readLibraries(context.root, rootPackage, libraries, merged, warn);
+	if (!libraries.length) {
+		const workspace = await findWorkspaceRoot(context.root);
+		if (workspace) await readLibraries(workspace.directory, workspace.pkg, libraries, merged, warn);
+	}
+	const patterns = strings(record(rootPackage.masterCSS).contracts);
+	const settingsFile = await readJSON(join(context.root, "master-ui.json"));
+	if ("value" in settingsFile) {
+		const settings = record(settingsFile.value);
+		patterns.push(`${text(settings.directory) ?? "ui"}/*.json`, ...strings(settings.contracts));
+	} else if (!settingsFile.missing) warn("CONTRACT_SETTINGS_UNREADABLE", `master-ui.json could not be read: ${settingsFile.error}`);
+	const accepted = [];
+	for (const pattern of new Set(patterns.map((pattern) => posix(pattern).replace(/^(?:\.\/)+/, "").replace(/\/{2,}/g, "/")))) try {
+		context.validateGlobPatterns([pattern]);
+		accepted.push(pattern);
+	} catch (error) {
+		warn("CONTRACT_PATTERN_REJECTED", getErrorMessage(error));
+	}
+	const files = accepted.length ? (await fg(accepted, {
+		cwd: context.root,
+		ignore: DEFAULT_IGNORE_PATTERNS,
+		onlyFiles: true,
+		followSymbolicLinks: false
+	})).sort() : [];
+	if (files.length > MAX_PROJECT_CONTRACT_FILES) {
+		warn("CONTRACT_FILES_TRUNCATED", `The project's contract patterns match ${files.length} files; only the first ${MAX_PROJECT_CONTRACT_FILES} are read.`);
+		files.length = MAX_PROJECT_CONTRACT_FILES;
+	}
+	for (const file of files) {
+		const filePath = await context.resolveExistingFile(file).catch(() => void 0);
+		const parsed = filePath ? await readJSON(filePath) : void 0;
+		if (!parsed || !("value" in parsed)) continue;
+		for (const contract of contractsIn(parsed.value)) {
+			const previous = merged.get(contract.name);
+			const replaces = previous?.source.kind === "package" ? {
+				package: previous.source.package,
+				version: previous.source.version
+			} : previous?.source.replaces;
+			merged.set(contract.name, {
+				contract,
+				source: {
+					kind: "project",
+					file: posix(file),
+					...replaces ? { replaces } : {}
+				},
+				library: previous?.library
+			});
+		}
+	}
+	const ownCheck = text(record(rootPackage.masterCSS).check);
+	if (ownCheck) {
+		const checkPath = await resolveInside(await realpath(context.root), ownCheck);
+		if (checkPath) {
+			const name = text(rootPackage.name) ?? "workspace";
+			const own = {
+				name,
+				version: text(rootPackage.version) ?? null,
+				count: 0,
+				checkPath
+			};
+			for (const item of merged.values()) if (item.source.kind === "project" && !item.library) {
+				item.library = name;
+				own.count++;
+			}
+			libraries.unshift(own);
+		} else warn("CONTRACT_CHECKER_UNRESOLVED", `The workspace package.json declares masterCSS.check "${ownCheck}", which is not a file inside the workspace.`);
+	}
+	return {
+		libraries,
+		contracts: [...merged.values()],
+		warnings
+	};
+}
+const describeLibrary = ({ name, version, count, checkPath }) => ({
+	name,
+	version,
+	count,
+	checker: Boolean(checkPath)
+});
+async function listContracts(context, options = {}) {
+	const discovery = await discoverContracts(context);
+	const terms = (options.query ?? "").toLowerCase().split(/\s+/).filter(Boolean);
+	const same = (value, expected) => !expected?.trim() || text(value)?.toLowerCase() === expected.trim().toLowerCase();
+	const matched = discovery.contracts.filter(({ contract }) => {
+		if (!same(contract.tier, options.tier) || !same(contract.category, options.category)) return false;
+		const searched = [
+			contract.name,
+			text(contract.title),
+			text(contract.description),
+			text(contract.use),
+			...classNamesOf(contract)
+		].join("\n").toLowerCase();
+		return terms.every((term) => searched.includes(term));
+	});
+	return {
+		version: CONTRACT_REPORT_VERSION,
+		root: context.root,
+		libraries: discovery.libraries.map(describeLibrary),
+		contracts: matched.map(({ contract, source }) => ({
+			name: contract.name,
+			title: text(contract.title),
+			tier: text(contract.tier),
+			category: text(contract.category),
+			description: text(contract.description),
+			use: text(contract.use),
+			script: text(contract.script),
+			source
+		})),
+		diagnostics: discovery.warnings,
+		summary: {
+			libraries: discovery.libraries.length,
+			contracts: discovery.contracts.length,
+			returned: matched.length
+		},
+		...discovery.contracts.length ? {} : { note: NO_CONTRACTS_NOTE }
+	};
+}
+function editDistance(a, b) {
+	let previous = Array.from({ length: b.length + 1 }, (_, index) => index);
+	for (let i = 1; i <= a.length; i++) {
+		const current = [i];
+		for (let j = 1; j <= b.length; j++) current[j] = Math.min(previous[j] + 1, current[j - 1] + 1, previous[j - 1] + (a[i - 1] === b[j - 1] ? 0 : 1));
+		previous = current;
+	}
+	return previous[b.length];
+}
+/** The names nearest to what was asked: one that contains it first, then a near spelling or a name it contains. */
+function closest(target, candidates, limit = 5) {
+	const wanted = target.toLowerCase();
+	return candidates.map((candidate) => {
+		const name = candidate.toLowerCase();
+		const gap = Math.abs(name.length - wanted.length) / 100;
+		return {
+			candidate,
+			distance: name.includes(wanted) ? gap : Math.min(editDistance(wanted, name), wanted.includes(name) ? 1 + gap : Infinity)
+		};
+	}).sort((a, b) => a.distance - b.distance || a.candidate.localeCompare(b.candidate)).slice(0, limit).map((item) => item.candidate);
+}
+async function getContract(context, options) {
+	const discovery = await discoverContracts(context);
+	const name = options.name.trim();
+	const byClass = /* @__PURE__ */ new Map();
+	for (const item of discovery.contracts) for (const className of classNamesOf(item.contract)) if (!byClass.has(className)) byClass.set(className, item);
+	const named = discovery.contracts.find((item) => item.contract.name === name);
+	const found = named ?? byClass.get(name);
+	if (!found) {
+		const classes = closest(name, [...byClass.keys()]);
+		const contracts = [.../* @__PURE__ */ new Set([...classes.slice(0, 2).map((className) => byClass.get(className).contract.name), ...closest(name, discovery.contracts.map((item) => item.contract.name))])].slice(0, 5);
+		const missing = `No contract is named "${name}" and no contract has a class "${name}".`;
+		const lookup = (message, alternatives) => ({
+			code: "CONTRACT_NOT_FOUND",
+			phase: "contract-lookup",
+			severity: "info",
+			message,
+			alternatives
+		});
+		throw Object.assign(/* @__PURE__ */ new Error(discovery.contracts.length ? `${missing} Closest contracts: ${contracts.join(", ")}. Closest classes: ${classes.join(", ")}. Call mastercss_contract_list for every contract.` : `${missing} ${NO_CONTRACTS_NOTE}`), {
+			code: "CONTRACT_NOT_FOUND",
+			diagnostics: [
+				...contracts.length ? [lookup("Closest contract names.", contracts)] : [],
+				...classes.length ? [lookup("Closest class names.", classes)] : [],
+				...discovery.warnings
+			]
+		});
+	}
+	return {
+		version: CONTRACT_REPORT_VERSION,
+		root: context.root,
+		name,
+		matched: named ? "contract" : "class",
+		contract: found.contract,
+		source: found.source,
+		diagnostics: discovery.warnings
+	};
+}
+const checkerFailure = (library, action, error) => Object.assign(/* @__PURE__ */ new Error(`The contract checker of ${library.name} ${action}: ${getErrorMessage(error)}`), { code: "CONTRACT_CHECKER_FAILED" });
+/**
+* The worker that runs one checker. It imports the module afresh, so an upgraded library needs no restart, and
+* the server can stop a checker that hangs or exhausts its memory. `knows` stays in the server: the worker asks
+* for each class it has not seen and waits for the answer, so a checker still calls it synchronously.
+*/
+const CHECKER_WORKER = `
+const { parentPort, workerData } = require('node:worker_threads')
+const { checkURL, contracts, signal } = workerData
+const answers = new Map()
+function knows(className) {
+  const key = String(className)
+  if (!answers.has(key)) {
+    Atomics.store(signal, 0, 0)
+    parentPort.postMessage({ type: 'knows', className: key })
+    Atomics.wait(signal, 0, 0)
+    answers.set(key, signal[1] === 1)
+  }
+  return answers.get(key)
+}
+const describe = error => error instanceof Error ? error.message : String(error)
+const loading = import(checkURL).then(module => {
+  if (typeof module.check !== 'function') throw new Error('the module does not export a check function')
+  return module.check
+})
+loading.then(() => parentPort.postMessage({ type: 'ready' }), error => parentPort.postMessage({ type: 'failed', message: describe(error) }))
+parentPort.on('message', async ({ content, strict, withKnows }) => {
+  try {
+    const reported = await (await loading)(content, contracts, withKnows ? { knows, strict } : { strict })
+    parentPort.postMessage(Array.isArray(reported)
+      ? { type: 'result', diagnostics: JSON.parse(JSON.stringify(reported.slice(0, ${MAX_DIAGNOSTICS_PER_FILE}))) }
+      : { type: 'failed', message: 'check() did not return an array of diagnostics' })
+  } catch (error) {
+    parentPort.postMessage({ type: 'failed', message: describe(error) })
+  }
+})
+`;
+/** Start the checker a library ships. Discovery already proved the file is inside that library. */
+async function startChecker(library, contracts, knows) {
+	const { timeoutMs, memoryMb } = contractCheckerLimits;
+	const signal = new Int32Array(new SharedArrayBuffer(8));
+	const worker = new Worker(CHECKER_WORKER, {
+		eval: true,
+		stdout: true,
+		workerData: {
+			checkURL: pathToFileURL(library.checkPath).href,
+			contracts,
+			signal
+		},
+		resourceLimits: { maxOldGenerationSizeMb: memoryMb }
+	});
+	worker.stdout.pipe(process.stderr, { end: false });
+	let waiting;
+	let ended;
+	const end = (error) => {
+		ended ??= error;
+		waiting?.reject(ended);
+		waiting = void 0;
+	};
+	worker.on("error", end);
+	worker.on("exit", (code) => end(/* @__PURE__ */ new Error(`its worker stopped with exit code ${code}`)));
+	worker.on("message", (message) => {
+		if (message.type === "knows") {
+			signal[1] = knows?.(String(message.className)) ? 1 : 0;
+			Atomics.store(signal, 0, 1);
+			Atomics.notify(signal, 0);
+			return;
+		}
+		const current = waiting;
+		waiting = void 0;
+		if (message.type === "failed") current?.reject(new Error(String(message.message)));
+		else current?.resolve(message);
+	});
+	/** The worker's next answer, or the reason it gave none within the time limit. */
+	const answer = (action, send) => new Promise((resolve, reject) => {
+		if (ended) return reject(ended);
+		const timer = setTimeout(() => {
+			end(/* @__PURE__ */ new Error(`did not finish within ${timeoutMs} ms`));
+			worker.terminate();
+		}, timeoutMs);
+		waiting = {
+			resolve: (message) => {
+				clearTimeout(timer);
+				resolve(message);
+			},
+			reject: (error) => {
+				clearTimeout(timer);
+				reject(error);
+			}
+		};
+		send?.();
+	}).catch((error) => {
+		throw checkerFailure(library, action, error);
+	});
+	const dispose = async () => {
+		ended ??= /* @__PURE__ */ new Error("its worker was stopped");
+		await worker.terminate();
+	};
+	try {
+		await answer("could not be loaded");
+	} catch (error) {
+		await dispose();
+		throw error;
+	}
+	return {
+		check: async (content, strict, filePath) => (await answer(`failed on ${filePath}`, () => worker.postMessage({
+			content,
+			strict,
+			withKnows: Boolean(knows)
+		}))).diagnostics,
+		dispose
+	};
+}
+function normalizeDiagnostic(value, source) {
+	const diagnostic = record(value);
+	if (typeof diagnostic.message !== "string") return [];
+	const position = (value) => typeof value === "number" && Number.isInteger(value) && value >= 0 ? value : 0;
+	const className = text(diagnostic.className);
+	const contract = text(diagnostic.contract);
+	return [{
+		code: text(diagnostic.code) ?? "contract",
+		severity: diagnostic.severity === "warning" || diagnostic.severity === "info" ? diagnostic.severity : "error",
+		message: diagnostic.message,
+		line: position(diagnostic.line),
+		column: position(diagnostic.column),
+		...className ? { className } : {},
+		...contract ? { contract } : {},
+		source
+	}];
+}
+async function readCheckInputs(context, options) {
+	const skippedFiles = [];
+	if (options.content !== void 0) return {
+		inputs: [{
+			filePath: context.resolveVirtualPath(options.filePath || "index.html"),
+			content: options.content
+		}],
+		skippedFiles
+	};
+	const filePaths = (await resolveSourceFiles(context, options.patterns, options.patterns ? [] : DEFAULT_IGNORE_PATTERNS, DEFAULT_CHECK_PATTERNS)).sort();
+	if (filePaths.length > MAX_CHECK_FILES) throw Object.assign(/* @__PURE__ */ new Error(`The patterns match ${filePaths.length} files; a contract check reads at most ${MAX_CHECK_FILES}. Pass narrower patterns.`), { code: "CONTRACT_CHECK_TOO_MANY_FILES" });
+	const inputs = [];
+	for (const filePath of filePaths) if ((await stat(filePath)).size > MAX_CHECK_FILE_BYTES) skippedFiles.push({
+		filePath,
+		reason: `larger than ${MAX_CHECK_FILE_BYTES} bytes`
+	});
+	else inputs.push({
+		filePath,
+		content: await readFile(filePath, "utf8")
+	});
+	return {
+		inputs,
+		skippedFiles
+	};
+}
+async function checkContracts(context, options = {}) {
+	const discovery = await discoverContracts(context);
+	const report = {
+		version: CONTRACT_REPORT_VERSION,
+		root: context.root,
+		libraries: discovery.libraries.map(describeLibrary)
+	};
+	const notChecked = (status, note) => ({
+		...report,
+		checkers: [],
+		classValidation: "none",
+		strict: false,
+		files: [],
+		diagnostics: discovery.warnings,
+		coverage: {
+			status,
+			checkedFiles: [],
+			skippedFiles: [],
+			description: `${note} No markup was checked; zero diagnostics does not verify any source.`
+		},
+		summary: {
+			checkedFiles: 0,
+			filesWithDiagnostics: 0,
+			diagnostics: 0,
+			errors: 0,
+			warnings: 0
+		},
+		note
+	});
+	if (!discovery.contracts.length) return notChecked("no-contracts", NO_CONTRACTS_NOTE);
+	const checking = discovery.libraries.filter((library) => library.checkPath);
+	if (!checking.length) return notChecked("no-checker", "Contracts were found, but no library declares a checker in \"masterCSS.check\". Read contracts with mastercss_contract_list and mastercss_contract_get.");
+	const groups = checking.map((library, index) => ({
+		library,
+		contracts: discovery.contracts.filter((item) => checking.some((other) => other.name === item.library) ? item.library === library.name : index === 0).map((item) => item.contract)
+	})).filter((group) => group.contracts.length);
+	const { inputs, skippedFiles } = await readCheckInputs(context, options);
+	const manifest = await loadWorkspaceManifest(context);
+	const session = manifest.status === "loaded" ? createMCPToolingSession(manifest.manifest, manifest.nativeClassNames) : void 0;
+	const checkers = [];
+	try {
+		let knows;
+		if (session) {
+			const native = new Set(manifest.nativeClassNames);
+			const known = /* @__PURE__ */ new Map();
+			knows = (className) => {
+				if (native.has(className)) return true;
+				let result = known.get(className);
+				if (result === void 0) {
+					try {
+						result = session.inspectClassName(className).matchStatus === "matched";
+					} catch {
+						result = false;
+					}
+					known.set(className, result);
+				}
+				return result;
+			};
+		}
+		const strict = Boolean(knows);
+		for (const group of groups) checkers.push({
+			...group,
+			...await startChecker(group.library, group.contracts, knows)
+		});
+		const results = [];
+		for (const input of inputs) {
+			const diagnostics = [];
+			for (const { library, check } of checkers) {
+				const reported = await check(input.content, strict, input.filePath);
+				diagnostics.push(...reported.flatMap((diagnostic) => normalizeDiagnostic(diagnostic, library.name)));
+			}
+			diagnostics.sort((a, b) => a.line - b.line || a.column - b.column);
+			results.push({
+				filePath: input.filePath,
+				diagnostics
+			});
+		}
+		const files = results.filter((file) => file.diagnostics.length);
+		const flat = files.flatMap((file) => file.diagnostics.map((diagnostic) => ({
+			...diagnostic,
+			phase: "contract-check",
+			filePath: file.filePath
+		})));
+		return {
+			...report,
+			manifest: manifestMetadata(manifest),
+			checkers: checkers.map(({ library, contracts }) => ({
+				package: library.name,
+				version: library.version,
+				contracts: contracts.length
+			})),
+			classValidation: knows ? "project-manifest" : "none",
+			strict,
+			files,
+			diagnostics: [...discovery.warnings, ...flat],
+			coverage: {
+				status: inputs.length ? "complete" : "no-inputs",
+				checkedFiles: inputs.map((input) => input.filePath),
+				skippedFiles,
+				description: inputs.length ? "Every path in checkedFiles was read by the checkers listed in checkers. The files array lists only files with diagnostics. A checker reads markup as written: classes built at run time, parts whose root lives in another file, and browser behavior are not checked." : "No markup inputs matched, so no checker ran. Zero diagnostics does not verify any source."
+			},
+			summary: {
+				checkedFiles: inputs.length,
+				filesWithDiagnostics: files.length,
+				diagnostics: flat.length,
+				errors: flat.filter((diagnostic) => diagnostic.severity === "error").length,
+				warnings: flat.filter((diagnostic) => diagnostic.severity === "warning").length
+			},
+			...knows ? {} : { note: `The project manifest could not be loaded (${manifest.status === "error" ? manifest.error : "unknown"}), so the checker cannot tell a utility from a misspelled class and ran without strict mode.` }
+		};
+	} finally {
+		await Promise.all(checkers.map((checker) => checker.dispose()));
+		session?.dispose();
+	}
+}
+export { MAX_CHECK_CONTENT_LENGTH, checkContracts, contractCheckerLimits, discoverContracts, getContract, listContracts };

package/dist/format.js

@@ -52,7 +52,7 @@ async function previewDirectiveFormat(context, options = {}) {
 				}
 			};
 		}
-		const files = await resolveSourceFiles(context, options.patterns ?? DEFAULT_DIRECTIVE_FORMAT_PATTERNS);
+		const files = await resolveSourceFiles(context, options.patterns, void 0, DEFAULT_DIRECTIVE_FORMAT_PATTERNS);
 		const formattedFiles = await Promise.all(files.map(async (filePath) => {
 			const content = await readFile(filePath, "utf8");
 			return formatContent(service, filePath, content, options.range);

package/dist/lint.js

@@ -4,7 +4,7 @@ import { readFile } from "node:fs/promises";
 import { createToolingSessionSync } from "@master/css-tooling/node";
 import { fixMasterCSSContent, lintMasterCSSContent, resolveMasterCSSLintRules, summarizeMasterCSSLintFiles } from "@master/css-tooling/lint";
 // src/lint.ts
-const DEFAULT_LINT_SOURCE_PATTERNS = ["**/*.{html,htm,js,jsx,cjs,ts,tsx,mts,cts,svelte,astro,vue,md,mdx,pug,php,css,scss,less}"];
+const DEFAULT_LINT_SOURCE_PATTERNS = ["**/*.{html,htm,js,mjs,jsx,cjs,ts,tsx,mts,cts,svelte,astro,vue,md,mdx,pug,php,css,scss,less}"];
 const DEFAULT_IGNORE_PATTERNS = ["**/node_modules/**", "node_modules"];
 const LINT_REPORT_VERSION = 5;
 async function loadLintState(context, options = {}) {
@@ -14,7 +14,7 @@ async function loadLintState(context, options = {}) {
 		manifest: requireWorkspaceManifest(manifest),
 		nativeClassNames: manifest.nativeClassNames
 	});
-	const files = await resolveSourceFiles(context, options.patterns ?? DEFAULT_LINT_SOURCE_PATTERNS, options.patterns ? [] : DEFAULT_IGNORE_PATTERNS);
+	const files = await resolveSourceFiles(context, options.patterns, options.patterns ? [] : DEFAULT_IGNORE_PATTERNS, DEFAULT_LINT_SOURCE_PATTERNS);
 	return {
 		rules,
 		manifest,

package/dist/output-schema.js

@@ -2,6 +2,7 @@ import { change, classDiff, completion, diagnostic, envelopeMetadata, inspection
 import { extractSummary, extractedFile, formatFile, formatSummary, lintCoverage, lintFile, lintSummary, previewSummary, scanSummary, scannedFile, scanner, stylesheets } from "./source-schema.js";
 import { projectComparison, projectSnapshot } from "./project-comparison-schema.js";
 import { designSystemReport } from "./design-system-schema.js";
+import { contractCheck, contractGet, contractList } from "./contract-schema.js";
 import * as z from "zod/v4";
 // src/output-schema.ts
 const object = z.record(z.string(), z.json());
@@ -178,7 +179,10 @@ const fields = {
 		manifest: metadata,
 		completions: z.array(completion),
 		total: z.number()
-	}
+	},
+	mastercss_contract_list: contractList,
+	mastercss_contract_get: contractGet,
+	mastercss_contract_check: contractCheck
 };
 function toolOutputSchema(name) {
 	if (!fields[name]) throw new Error(`Missing output schema for ${name}`);

package/dist/preview-write-lock.js

@@ -8,6 +8,19 @@ const NAME = /^(\d+)-[a-f0-9-]+\.json$/;
 function missing(error) {
 	return error?.code === "ENOENT";
 }
+const SHARING = /* @__PURE__ */ new Set([
+	"EPERM",
+	"EACCES",
+	"EBUSY"
+]);
+async function retrySharing(operation, deadline) {
+	while (true) try {
+		return await operation();
+	} catch (error) {
+		if (!SHARING.has(error?.code ?? "") || performance.now() >= deadline) throw error;
+		await setTimeout(5);
+	}
+}
 async function remove(file) {
 	try {
 		await unlink(file);
@@ -23,7 +36,7 @@ function alive(pid) {
 		return error.code !== "ESRCH";
 	}
 }
-async function tickets(directory) {
+async function tickets(directory, deadline) {
 	const entries = [];
 	for (const id of await readdir(directory)) {
 		const register = id.endsWith(".next") ? id.slice(0, -5) : id;
@@ -38,7 +51,7 @@ async function tickets(directory) {
 		if (id !== register) continue;
 		let text;
 		try {
-			text = await readFile(file, "utf8");
+			text = await retrySharing(() => readFile(file, "utf8"), deadline);
 		} catch (error) {
 			if (missing(error)) continue;
 			throw error;
@@ -65,21 +78,21 @@ async function withPreviewWriteLock(work, options = {}) {
 	});
 	const publish = async (value) => {
 		await writeFile(file + ".next", JSON.stringify(value), { mode: 384 });
-		await rename(file + ".next", file);
+		await retrySharing(() => rename(file + ".next", file), deadline);
 	};
 	try {
 		await publish({
 			choosing: true,
 			number: "0"
 		});
-		const number = (await tickets(directory)).reduce((max, peer) => peer.number > max ? peer.number : max, 0n) + 1n;
+		const number = (await tickets(directory, deadline)).reduce((max, peer) => peer.number > max ? peer.number : max, 0n) + 1n;
 		await publish({
 			choosing: false,
 			number: String(number)
 		});
 		while (true) {
 			if (performance.now() >= deadline) throw new Error("Timed out waiting for another MCP preview apply.");
-			if (!(await tickets(directory)).some((peer) => peer.id !== id && (peer.choosing || peer.number < number || peer.number === number && peer.id < id))) return await work();
+			if (!(await tickets(directory, deadline)).some((peer) => peer.id !== id && (peer.choosing || peer.number < number || peer.number === number && peer.id < id))) return await work();
 			await setTimeout(10);
 		}
 	} finally {

package/dist/scan.js

@@ -9,7 +9,13 @@ import { captureMasterCSSProject, createMasterCSSInspectionReport } from "@maste
 // src/scan.ts
 const DEFAULT_SOURCE_PATTERNS = ["**/*.{html,htm,js,jsx,mjs,cjs,ts,tsx,mts,cts,svelte,astro,vue,md,mdx,pug,php}"];
 const DEFAULT_IGNORE_PATTERNS = ["**/node_modules/**", "node_modules"];
-async function resolveSourceFiles(context, patterns = DEFAULT_SOURCE_PATTERNS, ignore = DEFAULT_IGNORE_PATTERNS) {
+/**
+* Resolve source files for a tool. Default patterns follow the source policy, which
+* skips ignored build output such as `dist/`; only patterns the caller was given
+* select ignored files explicitly.
+*/
+async function resolveSourceFiles(context, explicitPatterns, ignore = DEFAULT_IGNORE_PATTERNS, defaultPatterns = DEFAULT_SOURCE_PATTERNS) {
+	const patterns = [...explicitPatterns ?? defaultPatterns];
 	context.validateGlobPatterns(patterns);
 	const sources = await fg(patterns, {
 		cwd: context.root,
@@ -18,7 +24,7 @@ async function resolveSourceFiles(context, patterns = DEFAULT_SOURCE_PATTERNS, i
 		followSymbolicLinks: false
 	});
 	const policy = new SourcePolicy(context.root, { exclude: ignore });
-	return Promise.all(sources.filter((source) => policy.accepts(source, patterns !== DEFAULT_SOURCE_PATTERNS)).map((source) => context.resolveExistingFile(source)));
+	return Promise.all(sources.filter((source) => policy.accepts(source, explicitPatterns !== void 0)).map((source) => context.resolveExistingFile(source)));
 }
 async function scanProject(context, options = {}) {
 	if (options.designSystem && options.context === "preset") throw new Error("designSystem inspection requires project context; omit context or select \"project\".");

package/dist/server.js

@@ -14,6 +14,7 @@ import { projectSnapshot } from "./project-comparison-schema.js";
 import { designSystemOptions } from "./design-system-schema.js";
 import { toolOutputSchema } from "./output-schema.js";
 import { suggestClasses } from "./suggest.js";
+import { MAX_CHECK_CONTENT_LENGTH, checkContracts, getContract, listContracts } from "./contracts.js";
 import { readFileSync } from "node:fs";
 import { dirname, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
@@ -372,6 +373,50 @@ function registerTools(server, context) {
 			openWorldHint: false
 		}
 	}, async (input) => executeTool(() => suggestSyntax(context, input)));
+	server.registerTool("mastercss_contract_list", {
+		title: "List Design System Contracts",
+		description: "List the component contracts that the workspace's design-system dependencies declare in \"masterCSS.contracts\", merged with the project's own. Filter by query, tier, or category. Returns an empty list with a note when nothing declares contracts.",
+		inputSchema: {
+			query: z.string().optional(),
+			tier: z.string().optional(),
+			category: z.string().optional()
+		},
+		outputSchema: toolOutputSchema("mastercss_contract_list"),
+		annotations: {
+			readOnlyHint: true,
+			destructiveHint: false,
+			idempotentHint: true,
+			openWorldHint: false
+		}
+	}, async (input) => executeTool(() => listContracts(context, input)));
+	server.registerTool("mastercss_contract_get", {
+		title: "Get Design System Contract",
+		description: "Return one full contract and its source by contract name or by any class name the contract defines. Read it before writing that component's markup.",
+		inputSchema: { name: z.string().min(1) },
+		outputSchema: toolOutputSchema("mastercss_contract_get"),
+		annotations: {
+			readOnlyHint: true,
+			destructiveHint: false,
+			idempotentHint: true,
+			openWorldHint: false
+		}
+	}, async (input) => executeTool(() => getContract(context, input)));
+	server.registerTool("mastercss_contract_check", {
+		title: "Check Markup Against Contracts",
+		description: "Check an in-memory source buffer or project files against the merged contracts with the checker module a design-system dependency, or the workspace package itself, declares in \"masterCSS.check\". Runs that package's code in a worker thread with a time and memory limit. Does not write files; reports when no library provides a checker.",
+		inputSchema: {
+			content: z.string().max(MAX_CHECK_CONTENT_LENGTH).optional(),
+			filePath: z.string().optional(),
+			patterns: z.array(z.string()).optional()
+		},
+		outputSchema: toolOutputSchema("mastercss_contract_check"),
+		annotations: {
+			readOnlyHint: true,
+			destructiveHint: false,
+			idempotentHint: true,
+			openWorldHint: false
+		}
+	}, async (input) => executeTool(() => checkContracts(context, input)));
 	server.registerTool("mastercss_preview_fixes", {
 		title: "Preview Master CSS Fixes",
 		description: "Create a diff preview for lint fixes or generated CSS output and return a confirmation token.",

package/package.json

@@ -50,17 +50,17 @@
         "provenance": true
     },
     "dependencies": {
-        "@master/css": "2.1.1",
-        "@master/css-compiler": "2.1.1",
-        "@master/css-language-service": "2.1.1",
-        "@master/css-tooling": "2.1.1",
-        "@master/css-preset": "2.1.1",
-        "@master/css-schema": "2.1.1",
+        "@master/css": "2.1.3",
+        "@master/css-compiler": "2.1.3",
+        "@master/css-language-service": "2.1.3",
+        "@master/css-tooling": "2.1.3",
+        "@master/css-preset": "2.1.3",
+        "@master/css-schema": "2.1.3",
         "@modelcontextprotocol/sdk": "^1.32.2",
         "fast-glob": "^3.3.3",
         "vscode-languageserver-textdocument": "^1.0.16",
         "zod": "^4.6.7"
     },
-    "version": "2.1.1",
-    "gitHead": "5a42a239e242afd2722baf1d9dc82ba68114a898"
+    "version": "2.1.3",
+    "gitHead": "8eb81a6a72e733c43c799659e6493f3f464b8cf9"
 }