onsystem 0.4.0 → 0.6.0

package/dist/cli.js

@@ -1,154 +1,14 @@
 #!/usr/bin/env node
-import { A as CONFIG_FILES, G as unique, I as LEGACY_CONFIG_FILES, J as toPosix, K as matchesGlob, L as RULE_IDS, M as DEFAULT_DOCS, N as DEFAULT_SEVERITY, U as detectProject, V as rulesFor, W as plural, b as uncheckedNotice, c as componentFiles, d as tokenFiles, f as NAME, h as stderrLogger, j as ConfigError, m as silentLogger, n as loadTarget, p as VERSION, q as relativePath, t as serveStdio, u as loadDesignSystem, x as formatDiagnostics } from "./stdio-BcJth14k.js";
+import { A as toDtcg, B as DEFAULT_DOCS, C as updateBaseline, G as RULE_IDS, R as CONFIG_FILES, S as readBaseline, V as DEFAULT_SEVERITY, W as LEGACY_CONFIG_FILES, Z as rulesFor, _ as VERSION, _t as relativePath, at as detectProject, b as applyBaseline, c as silentLogger, et as LIBRARY_IDS, ft as plural, g as NAME, gt as matchesGlob, h as formatDiagnostics, ht as isInside, i as componentFiles, it as declaredConfig, k as toDesignMd, l as stderrLogger, m as uncheckedNotice, mt as unique, nt as PACKAGE_FIELD, o as loadDesignSystem, ot as findDesignSystemPackage, s as tokenFiles, st as isDesignSystemName, tt as libraryAdapter, v as BASELINE_FILE, vt as toPosix, w as writeBaseline, x as countBaseline, y as LEGACY_BASELINE_FILE, z as ConfigError } from "./design-system-A3pRX3Ka.js";
+import { t as serveStdio } from "./stdio-CEChNFLR.js";
+import { r as loadTarget } from "./workspace-CHvUwgz9.js";
 import fs from "node:fs";
 import path from "node:path";
 import { escapePath, glob } from "tinyglobby";
-import fs$1 from "node:fs/promises";
+import fsp from "node:fs/promises";
 import { spawnSync } from "node:child_process";
 import readline from "node:readline/promises";
 import { parseArgs } from "node:util";
-//#region src/baseline.ts
-const BASELINE_FILE = "onsystem.baseline.json";
-/** The baseline's name from before the rename to onsystem: still read when the new one is absent. */
-const LEGACY_BASELINE_FILE = "design-system-mcp.baseline.json";
-/**
-* A finding's identity within its file and rule: the offending text with
-* whitespace collapsed, and without the quotes of a string literal, so a
-* formatter switching quote style does not make every finding look new.
-*/
-function key(diagnostic) {
-	const text = diagnostic.source.replace(/\s+/g, " ").trim();
-	return (/^(['"`])(.*)\1$/.exec(text)?.[2] ?? text).slice(0, 200);
-}
-/** The baseline's entries, or undefined when the file does not exist. */
-function readBaseline(file) {
-	let text;
-	try {
-		text = fs.readFileSync(file, "utf8");
-	} catch (error) {
-		if (error.code === "ENOENT") return void 0;
-		throw new ConfigError(`Could not read baseline ${file}: ${error.message}`);
-	}
-	const invalid = (why) => new ConfigError(`${file} is not a valid onsystem baseline (${why}). Fix it, or delete it and run check --update-baseline.`);
-	let parsed;
-	try {
-		parsed = JSON.parse(text);
-	} catch (error) {
-		throw invalid(error.message);
-	}
-	if (!isObject(parsed) || parsed.version !== 1) throw invalid("expected \"version\": 1");
-	if (!isObject(parsed.files)) throw invalid("\"files\" must be an object");
-	const entries = /* @__PURE__ */ new Map();
-	for (const [name, rules] of Object.entries(parsed.files)) {
-		if (!isObject(rules)) throw invalid(`"${name}" must map rules to findings`);
-		const byRule = /* @__PURE__ */ new Map();
-		for (const [rule, sources] of Object.entries(rules)) {
-			if (!isObject(sources)) throw invalid(`"${name}" › "${rule}" must map findings to counts`);
-			const counts = /* @__PURE__ */ new Map();
-			for (const [source, count] of Object.entries(sources)) {
-				if (!Number.isInteger(count) || count < 1) throw invalid(`"${name}" › "${rule}" › "${source}" must be a positive whole number`);
-				counts.set(source, count);
-			}
-			byRule.set(rule, counts);
-		}
-		entries.set(name, byRule);
-	}
-	return entries;
-}
-/**
-* Removes the findings the baseline accepts for `file`. Within a file and
-* rule, each entry accepts that many findings with the same source text, in
-* order; any beyond the count are new. Entries of `disabled` rules are not
-* counted as fixed: the rule is off, not satisfied.
-*/
-function applyBaseline(baseline, file, result, disabled = /* @__PURE__ */ new Set()) {
-	const remaining = /* @__PURE__ */ new Map();
-	for (const [rule, sources] of baseline.get(file) ?? []) {
-		if (disabled.has(rule)) continue;
-		for (const [source, count] of sources) remaining.set(`${rule}\0${source}`, count);
-	}
-	const diagnostics = [];
-	let baselined = 0;
-	for (const diagnostic of result.diagnostics) {
-		const id = `${diagnostic.ruleId}\0${key(diagnostic)}`;
-		const left = remaining.get(id) ?? 0;
-		if (left > 0) {
-			remaining.set(id, left - 1);
-			baselined++;
-		} else diagnostics.push(diagnostic);
-	}
-	let fixed = 0;
-	for (const count of remaining.values()) fixed += count;
-	return {
-		result: {
-			...result,
-			diagnostics,
-			errorCount: diagnostics.filter((d) => d.severity === "error").length,
-			warningCount: diagnostics.filter((d) => d.severity === "warning").length
-		},
-		baselined,
-		fixed
-	};
-}
-/**
-* The baseline after a run over `checked` (file → its findings): those files
-* get exactly their current findings, plus their previous entries for
-* `disabled` rules; other files keep their entries while they still exist
-* under `root`.
-*/
-function updateBaseline(previous, checked, root, disabled = /* @__PURE__ */ new Set()) {
-	const disabledIn = typeof disabled === "function" ? disabled : () => disabled;
-	const next = /* @__PURE__ */ new Map();
-	for (const [file, rules] of previous ?? []) if (!checked.has(file) && fs.existsSync(path.resolve(root, file))) next.set(file, rules);
-	for (const [file, diagnostics] of checked) {
-		const rules = /* @__PURE__ */ new Map();
-		const off = disabledIn(file);
-		for (const [rule, sources] of previous?.get(file) ?? []) if (off.has(rule)) rules.set(rule, sources);
-		for (const diagnostic of diagnostics) {
-			let sources = rules.get(diagnostic.ruleId);
-			if (!sources) rules.set(diagnostic.ruleId, sources = /* @__PURE__ */ new Map());
-			const id = key(diagnostic);
-			sources.set(id, (sources.get(id) ?? 0) + 1);
-		}
-		if (rules.size) next.set(file, rules);
-	}
-	return next;
-}
-function countBaseline(entries) {
-	let findings = 0;
-	for (const rules of entries.values()) for (const sources of rules.values()) for (const count of sources.values()) findings += count;
-	return {
-		findings,
-		files: entries.size
-	};
-}
-/** Writes the baseline sorted at every level, so it diffs cleanly in review. */
-function writeBaseline(file, entries) {
-	const sorted = (map) => [...map].sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0);
-	const files = {};
-	for (const [name, rules] of sorted(entries)) {
-		const byRule = {};
-		for (const [rule, sources] of sorted(rules)) byRule[rule] = Object.fromEntries(sorted(sources));
-		Object.defineProperty(files, name, {
-			value: byRule,
-			enumerable: true,
-			writable: true
-		});
-	}
-	const baseline = {
-		version: 1,
-		files
-	};
-	try {
-		fs.writeFileSync(file, `${JSON.stringify(baseline, null, 2)}\n`);
-	} catch (error) {
-		throw new ConfigError(`Could not write baseline ${file}: ${error.message}`);
-	}
-}
-function isObject(value) {
-	return typeof value === "object" && value !== null && !Array.isArray(value);
-}
-//#endregion
 //#region src/explain.ts
 /**
 * What `inspect --explain` says about one project: every candidate zero config looked
@@ -160,24 +20,32 @@ function explainProject(ds, cwd, indent = "") {
 	const lines = [];
 	const out = (line = "") => lines.push(line ? `${indent}${line}` : "");
 	out("How the design system was found");
+	for (const step of packageSteps(config, cwd)) out(`  ${(step.accepted ? "found" : "no").padEnd(6)} ${step.candidate}: ${step.reason}`);
 	if (config.configured) out(`  components come from ${config.configFile ? display(cwd, config.configFile) : "--components"}, so zero config did not look`);
 	else {
 		const steps = [];
-		detectProject(config.root, config.tsconfig, steps);
+		detectProject(config.root, config.tsconfig, steps, config.designSystemPackage);
 		for (const step of steps) out(`  ${(step.accepted ? "found" : "no").padEnd(6)} ${step.candidate}: ${step.reason}`);
 		if (!config.detected) out(`  So the defaults apply: ${config.components.join(", ")}${model.stats.files.components ? "" : ", which match nothing"}.`);
 	}
+	const named = (library) => `${library.package}${library.version ? ` ${library.version}` : ""}`;
+	for (const library of config.libraries ?? []) {
+		const count = model.components.filter((c) => c.library === library.package).length;
+		out(library.dir ? `  ${"found".padEnd(6)} ${named(library)}: a dependency, ${count} components from its type declarations in ${display(cwd, library.dir)}` : `  ${"no".padEnd(6)} ${named(library)}: a dependency, but not installed`);
+	}
+	for (const library of config.librariesOff ?? []) out(`  ${"no".padEnd(6)} ${named(library)}: a dependency, ${librariesLeftOut(config, cwd)}`);
 	out();
 	out("Resolved config");
 	const field = (name, value) => out(`  ${name.padEnd(12)} ${value}`);
 	field("root", config.root);
-	field("config", config.configFile ? display(cwd, config.configFile) : "(none)");
+	field("config", config.configFile ? `${display(cwd, config.configFile)}${config.designSystemPackage ? ` (declared by ${config.designSystemPackage.name})` : ""}` : "(none)");
 	field("components", listOf$1(config.components) || "(none)");
 	field("exclude", listOf$1(config.exclude));
-	field("tokens", listOf$1(config.tokens.map((t) => `${t.path}${t.prefix ? ` (prefix ${t.prefix})` : ""}`)));
+	field("tokens", listOf$1(config.tokens.map((t) => `${t.path}${t.prefix ? ` (prefix ${t.prefix})` : ""}${t.fallback ? " (when nothing else is found)" : ""}`)));
 	field("docs", listOf$1(config.docs));
 	field("tsconfig", config.tsconfig ?? (fs.existsSync(path.join(config.root, "tsconfig.json")) ? "tsconfig.json" : "(none)"));
 	field("importPath", importPaths(ds));
+	field("libraries", config.libraryIds === void 0 ? `every library onsystem reads (${LIBRARY_IDS.join(", ")})` : config.libraryIds !== false && config.libraryIds.length ? config.libraryIds.join(", ") : `none ("libraries": ${JSON.stringify(config.libraryIds)})`);
 	if (config.tailwindConfig) field("tailwind", display(config.root, config.tailwindConfig));
 	if (config.designSystems) field("primary", config.designSystems.map((d, i) => `${i ? "then " : ""}${d.source} (${d.imports} imports)`).join("; "));
 	const changed = RULE_IDS.filter((id) => config.rules[id].severity !== DEFAULT_SEVERITY[id]);
@@ -188,7 +56,12 @@ function explainProject(ds, cwd, indent = "") {
 	out("Tokens");
 	const found = ds.tokens;
 	const files = model.stats.files.tokens;
-	out(`  ${found.length} tokens from ${files} ${files === 1 ? "file" : "files"}${files ? "" : `: no file matches ${config.tokens.map((t) => t.path).join(", ")}`}`);
+	const themed = found.filter((t) => t.origin === "library");
+	out(`  ${found.length - themed.length} tokens from ${files} ${files === 1 ? "file" : "files"}${files ? "" : `: no file matches ${config.tokens.map((t) => t.path).join(", ")}`}`);
+	if (themed.length) {
+		const sources = [...new Set(themed.map((t) => t.source.file))];
+		out(`  ${themed.length} tokens from a library's theme in ${sources.join(", ")}`);
+	}
 	const defined = new Set(found.map((t) => t.cssVar).filter((v) => Boolean(v)));
 	const missing = (value) => [...value.matchAll(/var\(\s*(--[\w-]+)/g)].map((m) => m[1] ?? "").filter((v) => !defined.has(v));
 	const unresolved = found.filter((t) => missing(t.value).length);
@@ -209,6 +82,10 @@ function explainProject(ds, cwd, indent = "") {
 	}
 	return lines;
 }
+/** Why a library the project depends on is not read: `left out by "libraries" in onsystem.config.json`. */
+function librariesLeftOut(config, cwd) {
+	return `left out by "libraries" in ${config.configFile ? display(cwd, config.configFile) : "the config"}`;
+}
 /** The first few, then how many more: a package's exports can name hundreds of files. */
 function listOf$1(items, max = 8) {
 	const shown = items.slice(0, max).join(", ");
@@ -235,15 +112,46 @@ function display(cwd, file) {
 	const rel = relativePath(cwd, file);
 	return rel && !rel.startsWith("..") ? rel : file;
 }
+/**
+* Whether a dependency's declared config was taken on, for a project without a config of its
+* own: the package it came from and the others that declare one, or that none does.
+*/
+function packageSteps(config, cwd) {
+	const declared = config.designSystemPackage;
+	if (config.configFile && !declared) return [];
+	const lookup = findDesignSystemPackage(config.root);
+	if (!lookup) return [];
+	const candidate = "a design-system package's config";
+	const skipped = lookup.skipped.length ? `; ${lookup.skipped.map((p) => p.name).join(", ")} ${lookup.skipped.length === 1 ? "declares one" : "declare one"} that cannot be read, skipped since installed` : "";
+	if (!declared) return [{
+		candidate,
+		accepted: false,
+		reason: `no dependency declares one ("onsystem" in its package.json) among ${lookup.dependencies} ${lookup.dependencies === 1 ? "dependency" : "dependencies"}${skipped}`
+	}];
+	return [{
+		candidate,
+		accepted: true,
+		reason: `${declared.name} (${declared.installed ? "installed" : "a workspace package"}) declares ${display(cwd, declared.config)}, which this project takes on, with its paths from ${display(cwd, declared.dir)}${lookup.others.length ? `; ${lookup.others.join(", ")} also declare one, not read: one config is taken on, from the package the code imports most` : ""}${skipped}`
+	}];
+}
 //#endregion
 //#region src/init.ts
 const SCHEMA = "https://unpkg.com/onsystem/schema.json";
 /** More detected globs than this are files, not folders: zero config keeps them. */
 const MAX_GLOBS = 6;
+/** What a design-system package's apps are told about it, next to its config. */
+const GUIDE_FILE = "ONSYSTEM.md";
 /**
 * Writes `onsystem.config.json` in the root from what zero config finds there, or from
 * the answers to up to three questions when it finds nothing, then checks the project
 * once without failing and offers to record what it found as the baseline.
+*
+* In a design-system package (one zero config reads through its own `exports`, or named like
+* one, as apps look for it), it also declares the config in package.json
+* (`"onsystem": "./onsystem.config.json"`, and in `files` when the package lists them), so
+* every app that depends on the package reads it, and writes ONSYSTEM.md, which tells those
+* apps' teams how to add the agent tools and the CI check. In an app that takes on such a
+* package's config, it writes no config of its own unless --force says to.
 */
 async function init(configOptions, options, io, runCheck) {
 	const { config, workspace } = await loadTarget({
@@ -251,16 +159,23 @@ async function init(configOptions, options, io, runCheck) {
 		config: void 0
 	});
 	const root = config.root;
-	const existing = [...CONFIG_FILES, ...LEGACY_CONFIG_FILES].map((name) => path.join(root, name)).find((file) => fs.existsSync(file));
+	const declared = declaredConfig(root);
+	const existing = [...CONFIG_FILES, ...LEGACY_CONFIG_FILES].map((name) => path.join(root, name)).find((file) => fs.existsSync(file)) ?? (declared && "file" in declared ? declared.file : void 0);
+	const manifest = readManifest(root);
+	const name = typeof manifest?.json.name === "string" ? manifest.json.name : void 0;
+	const designSystem = !workspace && !config.designSystemPackage && name !== void 0 && (config.detected?.startsWith("package.json exports of") === true || isDesignSystemName(name));
 	if (existing && !options.force) {
-		io.stderr(`init: ${relativePath(io.cwd, existing) || existing} already exists. Run \`${NAME} inspect --explain\` to see what it resolves to, or pass --force to write a new onsystem.config.json.`);
+		const share = designSystem && !declared && existing.endsWith(".json") ? ` To share it with the apps that depend on ${name}, add "${PACKAGE_FIELD}": "./${path.basename(existing)}" to package.json, and to "files" when it lists them (https://onsystem.vercel.app/docs/design-system-packages).` : "";
+		io.stderr(`init: ${relativePath(io.cwd, existing) || existing} already exists. Run \`${NAME} inspect --explain\` to see what it resolves to, or pass --force to write a new onsystem.config.json.${share}`);
 		return 2;
 	}
 	const ask = options.yes ? void 0 : io.prompt;
 	const file = { $schema: SCHEMA };
 	const notes = [];
 	const relative = (abs) => relativePath(root, abs);
-	if (configOptions.components?.length) {
+	const inherited = options.force ? void 0 : config.designSystemPackage;
+	if (inherited) notes.push(`This project takes on the config ${inherited.name} declares in its package.json (${relativePath(io.cwd, inherited.config) || inherited.config}), so it needs none of its own; nothing was written. Pass --force to write one, which is read instead.`);
+	else if (configOptions.components?.length) {
 		file.components = configOptions.components;
 		if (configOptions.tokens?.length) file.tokens = configOptions.tokens;
 		if (configOptions.docs?.length) file.docs = configOptions.docs;
@@ -278,6 +193,16 @@ async function init(configOptions, options, io, runCheck) {
 			if (docs.length) file.docs = [...DEFAULT_DOCS, ...docs];
 		}
 		if (tokens.length) file.tokens = tokens;
+	} else if ((await componentFiles(config)).length) {
+		const matching = [];
+		for (const glob of config.components) if ((await componentFiles({
+			...config,
+			components: [glob]
+		})).length) matching.push(glob);
+		notes.push(`Found the design system in the default folders: ${matching.join(", ")}.`);
+		file.components = matching;
+		const tokens = (await tokenFiles(config)).map(relative);
+		if (tokens.length) file.tokens = tokens;
 	} else {
 		if (!ask) {
 			io.stderr(`init: zero config found no design system in ${root}. Pass --components (and --tokens) to say where it is, or run init in a terminal to answer a few questions. \`${NAME} inspect --explain\` shows what it looked at.`);
@@ -307,10 +232,19 @@ async function init(configOptions, options, io, runCheck) {
 		const importPath = (await ask("How do apps import them? A package name such as @acme/ui, or leave it empty for tsconfig paths: ")).trim();
 		if (importPath) file.importPath = importPath;
 	}
-	const out = path.join(root, "onsystem.config.json");
-	fs.writeFileSync(out, `${JSON.stringify(file, null, 2)}\n`);
+	const written = [];
+	if (!inherited) {
+		const out = path.join(root, CONFIG_FILE);
+		fs.writeFileSync(out, `${JSON.stringify(file, null, 2)}\n`);
+		written.push(CONFIG_FILE);
+	}
+	if (designSystem && manifest && name) {
+		written.push(...declarePackage(root, manifest, name, options.force, notes));
+		const shipped = await unshipped(config, manifest.json);
+		if (shipped) notes.push(shipped);
+	}
 	for (const note of notes) io.stdout(note);
-	io.stdout(`Wrote ${relativePath(io.cwd, out) || out}.`);
+	if (written.length) io.stdout(`Wrote ${written.map((f) => relativePath(io.cwd, path.join(root, f)) || f).join(", ")}.`);
 	const checkIo = {
 		...io,
 		cwd: root
@@ -342,9 +276,11 @@ async function init(configOptions, options, io, runCheck) {
 	io.stdout(total ? `Dry run of \`${NAME} check .\`: ${count$1(errors, "error")} and ${count$1(warnings, "warning")} in ${flagged} of ${count$1(results.length, "file")}. By rule: ${[...byRule].sort((a, b) => b[1] - a[1]).map(([rule, n]) => `${rule} ${n.toLocaleString("en-US")}`).join(", ")}.` : `Dry run of \`${NAME} check .\`: no problems in ${count$1(results.length, "file")}.`);
 	for (const line of dry.stderr.split("\n").filter(Boolean)) io.stdout(line);
 	const hasBaseline = [BASELINE_FILE, LEGACY_BASELINE_FILE].some((name) => fs.existsSync(path.join(root, name)));
+	let baselineWritten = false;
 	if (total && !hasBaseline) {
-		const answer = options.yes ? "y" : ask ? (await ask(`Record these ${total.toLocaleString("en-US")} findings in ${BASELINE_FILE}, so check fails only on new ones? [Y/n] `)).trim().toLowerCase() : "n";
-		if (answer === "" || answer.startsWith("y")) {
+		const answer = options.yes ? "y" : ask ? (await ask(`Record these ${total.toLocaleString("en-US")} findings in ${BASELINE_FILE}, so check fails only on new ones? [Y/n] `)).trim().toLowerCase() : void 0;
+		if (answer === void 0) io.stdout(`No terminal to ask in, so the baseline question was skipped and no baseline was written; \`${NAME} check . --update-baseline\` records one.`);
+		else if (answer === "" || answer.startsWith("y")) {
 			const recorded = await runCheck([
 				"check",
 				".",
@@ -352,17 +288,134 @@ async function init(configOptions, options, io, runCheck) {
 				...options.cache ? [] : ["--no-cache"]
 			], checkIo);
 			if (recorded.stdout) io.stdout(recorded.stdout);
+			baselineWritten = fs.existsSync(path.join(root, BASELINE_FILE));
 		} else io.stdout(`No baseline written; \`${NAME} check . --update-baseline\` records one later.`);
 	}
-	io.stdout(`Next: commit onsystem.config.json${total && !hasBaseline ? ` and ${BASELINE_FILE}` : ""}, and run \`npx ${NAME} check . --format github --require-design-system\` in CI.`);
+	const commit = [...written, ...baselineWritten ? [BASELINE_FILE] : []];
+	const files = commit.length > 1 ? `${commit.slice(0, -1).join(", ")} and ${commit.at(-1) ?? ""}` : commit[0];
+	io.stdout(designSystem && name ? `Next: commit ${files}. An app that depends on ${name} now finds it with no config of its own: run \`npx ${NAME} inspect\` in one to see it, and give its team ${GUIDE_FILE}.` : `Next: ${files ? `commit ${files}, and ` : ""}run \`npx ${NAME} check . --format github --require-design-system\` in CI.`);
 	return 0;
 }
+const CONFIG_FILE = "onsystem.config.json";
+function readManifest(root) {
+	const file = path.join(root, "package.json");
+	try {
+		const text = fs.readFileSync(file, "utf8");
+		const json = JSON.parse(text);
+		if (!json || typeof json !== "object" || Array.isArray(json)) return void 0;
+		return {
+			file,
+			json,
+			indent: /^([ \t]+)"/m.exec(text)?.[1] ?? "  ",
+			newline: text.endsWith("\n")
+		};
+	} catch {
+		return;
+	}
+}
+/**
+* Declares the config in the package's package.json, `"onsystem": "./onsystem.config.json"`,
+* and adds it to `files` when the package lists the files it publishes, so apps that install it
+* get it too. Writes ONSYSTEM.md for the apps' teams unless one exists. Returns what it wrote.
+*/
+function declarePackage(root, manifest, name, force, notes) {
+	const written = [];
+	const { json } = manifest;
+	const value = `./${CONFIG_FILE}`;
+	let changed = false;
+	if (json["onsystem"] !== value) {
+		json[PACKAGE_FIELD] = value;
+		changed = true;
+	}
+	const files = Array.isArray(json.files) ? json.files : void 0;
+	if (files && !ships(files, CONFIG_FILE)) {
+		files.push(CONFIG_FILE);
+		changed = true;
+	}
+	if (changed) {
+		fs.writeFileSync(manifest.file, `${JSON.stringify(json, null, manifest.indent)}${manifest.newline ? "\n" : ""}`);
+		written.push("package.json");
+	}
+	notes.push(`This is a design-system package: package.json declares its config ("${PACKAGE_FIELD}": "${value}"${files ? ", also added to \"files\"" : ""}), which every app that depends on ${name} reads when it has no config of its own.`);
+	const guide = path.join(root, GUIDE_FILE);
+	if (force || !fs.existsSync(guide)) {
+		fs.writeFileSync(guide, consumerGuide(name));
+		written.push(GUIDE_FILE);
+	} else notes.push(`${GUIDE_FILE} already exists; it was left as it is (--force replaces it).`);
+	return written;
+}
+/**
+* What apps that install the package from a registry will not find: the component and token
+* files its `files` list leaves out of the published package. Undefined for a private package,
+* one without a `files` list (npm then ships everything), or when nothing is left out.
+*/
+async function unshipped(config, json) {
+	if (json.private === true || !Array.isArray(json.files)) return void 0;
+	const files = json.files;
+	const missing = [...await componentFiles(config), ...await tokenFiles(config)].map((f) => relativePath(config.root, f)).filter((f) => !f.startsWith("../")).filter((f) => !ships(files, f));
+	if (!missing.length) return void 0;
+	const folders = [...new Set(missing.map((f) => f.includes("/") ? `${f.slice(0, f.indexOf("/"))}/` : f))];
+	return `Apps that install ${typeof json.name === "string" ? json.name : "the package"} from a registry get only what "files" in package.json publishes, which leaves out ${folders.join(", ")} (${count$1(missing.length, "component or token file")}): they will not find those. Add ${folders.length === 1 ? "it" : "them"} to "files" for them; workspace apps read the sources either way.`;
+}
+/** Whether npm's `files` list publishes `file`, a path relative to the package. */
+function ships(files, file) {
+	return files.some((entry) => {
+		if (typeof entry !== "string") return false;
+		const pattern = entry.replace(/^\.?\//, "").replace(/\/+$/, "");
+		if (!pattern || pattern.startsWith("!")) return false;
+		return file === pattern || file.startsWith(`${pattern}/`) || matchesGlob(file, pattern) || matchesGlob(file, `${pattern}/**`);
+	});
+}
+/** ONSYSTEM.md: how an app that uses the package gets the design system to its agents and CI. */
+function consumerGuide(name) {
+	return `${[
+		`# onsystem in apps that use ${name}`,
+		"",
+		`${name} declares its [onsystem](https://onsystem.vercel.app) config in its package.json: \`"${PACKAGE_FIELD}": "./${CONFIG_FILE}"\`. An app that depends on ${name}, as a workspace package or installed from npm, reads that config when it has none of its own, and its UI is checked against ${name}'s components, props, variants and tokens. To see what an app finds, run this in its folder:`,
+		"",
+		"```sh",
+		`npx -y ${NAME} inspect`,
+		"```",
+		"",
+		`An app with an ${CONFIG_FILE} of its own reads that instead.`,
+		"",
+		"## Coding agents",
+		"",
+		"Claude Code: the plugin checks every UI file the agent writes and hands the errors back to fix, and adds the MCP server and a skill.",
+		"",
+		"```text",
+		"/plugin marketplace add dgesteves/onsystem",
+		"/plugin install onsystem@dgesteves",
+		"```",
+		"",
+		`Other agents: \`npx skills add dgesteves/onsystem\` adds the skill, and \`npx -y ${NAME}\` started in the app is the MCP server. [Set up your agent](https://onsystem.vercel.app/docs/clients) has the config for each client.`,
+		"",
+		"## CI",
+		"",
+		"In the app, record the findings it already has once, and commit the baseline, so pull requests fail only on new ones:",
+		"",
+		"```sh",
+		`npm install --save-dev ${NAME}`,
+		`npx ${NAME} check . --update-baseline`,
+		"```",
+		"",
+		"```yaml",
+		`- run: npx ${NAME} check . --format github --require-design-system`,
+		"```",
+		"",
+		"[CI and baselines](https://onsystem.vercel.app/docs/ci) has the GitHub Action and the rest.",
+		"",
+		"## Changing the config",
+		"",
+		`${CONFIG_FILE} in ${name} sets what every app gets: where the components, tokens and docs are, and the rules' severities. Its \`tsconfig\`, \`overrides\` and \`includeDesignSystem\` apply to ${name}'s own files only. [Design-system packages](https://onsystem.vercel.app/docs/design-system-packages) has the details.`
+	].join("\n")}\n`;
+}
 function count$1(n, word) {
 	return `${n.toLocaleString("en-US")} ${n === 1 ? word : `${word}s`}`;
 }
 //#endregion
 //#region src/cli.ts
-const DOCS = "https://design-system-mcp-demo.vercel.app/docs";
+const DOCS = "https://onsystem.vercel.app/docs";
 const HELP = `${NAME} ${VERSION}
 
 Keeps coding agents on your React design system: checks UI code against your
@@ -374,6 +427,9 @@ Usage
   onsystem check <paths...>      Lint files, folders or globs with the check_ui rules
                                  (for CI)
   onsystem inspect               Print what was extracted from the project
+  onsystem export --format dtcg|design-md
+                                 Print the tokens it found as a DTCG 2025.10 file or a
+                                 DESIGN.md (--out <file> writes them to a file)
   onsystem init                  Write onsystem.config.json from what was found, run a
                                  dry-run check and offer a baseline
   onsystem help                  Show this help
@@ -392,7 +448,9 @@ Options
   --docs <glob>           Component docs (Markdown/MDX), repeatable
   --no-cache              Ignore the on-disk extraction cache
   --no-watch              serve: do not reload when files change
-  --format <format>       check: pretty | json | github (default: pretty)
+  --format <format>       check: pretty | json | github | sarif (default: pretty);
+                          export: dtcg | design-md
+  --out <file>            export: write to this file instead of stdout
   --max-warnings <n>      check: exit 1 when there are more than n warnings
   --update-baseline       check: record the current findings as accepted, and exit 0
   --baseline <file>       check: baseline file (default: ${BASELINE_FILE} in the root,
@@ -432,7 +490,8 @@ const defaultIo = {
 	stdout: (text) => process.stdout.write(`${text}\n`),
 	stderr: (text) => process.stderr.write(`${text}\n`),
 	color: process.stdout.isTTY && !process.env.NO_COLOR,
-	prompt: process.stdin.isTTY && process.stdout.isTTY ? askInTerminal : void 0
+	prompt: process.stdin.isTTY && process.stdout.isTTY ? askInTerminal : void 0,
+	stdinIsTTY: process.stdin.isTTY
 };
 /** One question on the terminal, answered with a line. */
 async function askInTerminal(question) {
@@ -477,10 +536,8 @@ async function main(argv, io = defaultIo) {
 					type: "boolean",
 					default: true
 				},
-				format: {
-					type: "string",
-					default: "pretty"
-				},
+				format: { type: "string" },
+				out: { type: "string" },
 				"max-warnings": { type: "string" },
 				baseline: { type: "string" },
 				"update-baseline": {
@@ -562,15 +619,18 @@ async function main(argv, io = defaultIo) {
 	try {
 		switch (command) {
 			case "serve":
+				if (io.stdinIsTTY) io.stderr(`${NAME} is an MCP server: it is waiting for an agent on stdin. Add it to your agent (${DOCS}/clients), or run \`npx -y ${NAME} inspect\` or \`npx -y ${NAME} check .\` here. Ctrl+C quits.`);
 				await serveStdio({
 					...configOptions,
 					cache: values.cache,
 					watch: values.watch,
-					logger: stderrLogger
+					logger: stderrLogger,
+					...io.transport ? { transport: io.transport } : {}
 				});
 				return 0;
 			case "check": return await check(rest, configOptions, values, io);
 			case "inspect": return await inspect(configOptions, values, io);
+			case "export": return await exportTokens(configOptions, values, io);
 			case "init": return await init(configOptions, {
 				yes: values.yes,
 				force: values.force,
@@ -610,13 +670,14 @@ async function check(patterns, configOptions, values, io) {
 		io.stderr(`check: pass files, folders or globs, e.g. ${NAME} check .`);
 		return 2;
 	}
-	const format = values.format;
+	const format = values.format ?? "pretty";
 	if (![
 		"pretty",
 		"json",
-		"github"
+		"github",
+		"sarif"
 	].includes(format)) {
-		io.stderr(`check: unknown --format "${values.format}" (pretty, json, github)`);
+		io.stderr(`check: unknown --format "${format}" (pretty, json, github, sarif)`);
 		return 2;
 	}
 	const maxWarnings = values["max-warnings"] === void 0 ? void 0 : Number(values["max-warnings"]);
@@ -626,15 +687,15 @@ async function check(patterns, configOptions, values, io) {
 	}
 	const target = await loadTarget(configOptions);
 	warnDeprecated(target.config.deprecations, format, io);
+	warnDeprecated(configWarnings(target), format, io);
 	const selection = target.workspace ? await selectInWorkspace(target.workspace, patterns, values, format, io) : await selectInProject(target.config, patterns, values, format, io);
 	if (typeof selection === "number") return selection;
 	const { files, notes } = selection;
 	if (!files.length) {
-		if (format === "json") io.stdout("[]");
-		else if (format === "pretty") {
+		if (format === "pretty") {
 			const hints = [selection.skipped ? `Pass --include-design-system to check ${selection.skipped === 1 ? "it" : "them"}.` : "", selection.testsLeftOut ? "Pass --include-tests to check tests and stories." : ""].filter(Boolean);
 			io.stdout(`Nothing to check: ${notes.join("; ")}. ${hints.join(" ")}`.trimEnd());
-		}
+		} else printNoResults(format, io);
 		return 0;
 	}
 	const update = values["update-baseline"];
@@ -658,7 +719,7 @@ async function check(patterns, configOptions, values, io) {
 	let baselined = 0;
 	let fixed = 0;
 	for (const file of files) {
-		const code = await fs$1.readFile(file, "utf8");
+		const code = await fsp.readFile(file, "utf8");
 		const ds = selection.designSystemOf(file);
 		let result = ds.check(code, relativePath(ds.root, file));
 		const key = baselineKey(file);
@@ -693,6 +754,7 @@ async function check(patterns, configOptions, values, io) {
 	}
 	const output = formatDiagnostics(format === "json" ? results : results.filter((r) => !r.skipped), format, {
 		color: io.color,
+		uri: format === "sarif" || format === "github" ? repositoryPath(io.cwd, io.env ?? process.env) : void 0,
 		baselined: baseline ? baselined : void 0,
 		notes,
 		fixedHint: fixed ? `${count(fixed, "baseline finding")} no longer ${fixed === 1 ? "occurs" : "occur"}: run \`check ${patterns.map(shellQuote).join(" ")} --update-baseline\` to drop ${fixed === 1 ? "it" : "them"}.` : void 0
@@ -713,6 +775,35 @@ async function check(patterns, configOptions, values, io) {
 	}
 	return 0;
 }
+/** What `json` and `sarif` print when there is nothing to report on: `[]`, or a log without results. */
+function printNoResults(format, io) {
+	if (format === "json") io.stdout("[]");
+	else if (format === "sarif") io.stdout(formatDiagnostics([], "sarif"));
+}
+/**
+* Maps a path relative to the working directory to one relative to the repository root, which
+* GitHub resolves workflow command annotations (`--format github`) and code scanning locations
+* (`--format sarif`) against, so `check` run from `apps/web` still reports
+* `apps/web/app/page.tsx`. The root is GITHUB_WORKSPACE or the git top-level, whichever is the
+* innermost folder holding the file: the git top-level outside Actions, GITHUB_WORKSPACE where
+* git is missing or refuses the checkout, and the repository checked out in a folder of the
+* workspace (`actions/checkout` with `path:`). A file under neither keeps its path relative to
+* the working directory.
+*/
+function repositoryPath(cwd, env) {
+	const result = spawnSync("git", ["rev-parse", "--show-toplevel"], {
+		cwd,
+		encoding: "utf8",
+		windowsHide: true
+	});
+	const roots = [result.status === 0 && typeof result.stdout === "string" ? result.stdout.trim() : "", env.GITHUB_WORKSPACE ?? ""].filter(Boolean).map((dir) => realPath(path.resolve(cwd, dir))).sort((a, b) => b.length - a.length);
+	if (!roots.length) return toPosix;
+	return (file) => {
+		const absolute = realPath(path.resolve(cwd, file));
+		const root = roots.find((dir) => isInside(dir, absolute));
+		return root ? relativePath(root, absolute) : toPosix(file);
+	};
+}
 /** Splits the patterns into files named outright and globs (a folder: every TSX/JSX file under it). */
 function expandPatterns(patterns, cwd) {
 	const named = [];
@@ -766,11 +857,11 @@ async function selectInProject(config, patterns, values, format, io) {
 		return 2;
 	}
 	if (values["quiet-without-design-system"] && !config.configFile && !ds.components.length) {
-		if (format === "json") io.stdout("[]");
+		printNoResults(format, io);
 		return 0;
 	}
 	const notice = ds.notice();
-	if (notice && values["require-design-system"]) {
+	if (notice && values["require-design-system"] && !ds.hasDesignSystem()) {
 		io.stderr(`check --require-design-system: ${notice}`);
 		return 2;
 	}
@@ -851,13 +942,13 @@ async function selectInWorkspace(workspace, patterns, values, format, io) {
 	if (values["quiet-without-design-system"]) {
 		files = files.filter((file) => Boolean(project(file).config.configFile) || designSystemOf(file).components.length > 0);
 		if (!files.length) {
-			if (format === "json") io.stdout("[]");
+			printNoResults(format, io);
 			return 0;
 		}
 	}
 	if (values["require-design-system"]) {
 		let complete = false;
-		for (const p of workspace.projects) if (!(await load(p)).notice()) {
+		for (const p of workspace.projects) if ((await load(p)).hasDesignSystem()) {
 			complete = true;
 			break;
 		}
@@ -909,6 +1000,7 @@ async function inspect(configOptions, values, io) {
 	const target = await loadTarget(configOptions);
 	const { config } = target;
 	warnDeprecated(config.deprecations, "pretty", io);
+	warnDeprecated(configWarnings(target), "pretty", io);
 	if (target.workspace) return inspectWorkspace(target.workspace, values, io);
 	const ds = await loadDesignSystem(config, {
 		cache: values.cache,
@@ -921,12 +1013,13 @@ async function inspect(configOptions, values, io) {
 	}
 	const lines = [
 		`root     ${model.root}`,
-		`config   ${config.configFile ? displayPath(io.cwd, config.configFile) : "(defaults)"}`,
+		`config   ${config.configFile ? `${displayPath(io.cwd, config.configFile)}${declaredBy(config)}` : "(defaults)"}`,
 		...config.detected ? [`detected ${config.detected}`] : [],
+		...describeLibraries(config, model, io.cwd).map((line) => `library  ${line}`),
 		`files    ${plural(model.stats.files.components, "component file")}, ${plural(model.stats.files.tokens, "token file")}, ${plural(model.stats.files.docs, "doc")}`,
 		`time     ${model.stats.durationMs}ms${model.stats.fromCache ? " (cache)" : ""}`,
 		"",
-		`Components (${ds.roots().length} + ${model.components.length - ds.roots().length} parts)`
+		`Components (${ds.roots().length} + ${ds.components.length - ds.roots().length} parts)`
 	];
 	for (const c of ds.roots()) {
 		const variants = c.variants.map((v) => `${v.name}[${v.values.length}]`).join(" ");
@@ -950,6 +1043,64 @@ async function inspect(configOptions, values, io) {
 	io.stdout(lines.join("\n"));
 	return 0;
 }
+/**
+* `MUI (@mui/material 9.4.0): 149 components from its type declarations`, per library the
+* project depends on, including those the config's `libraries` leaves out.
+*/
+function describeLibraries(config, model, cwd) {
+	const name = (library) => `${libraryAdapter(library.package)?.title ?? library.package} (${library.package}${library.version ? ` ${library.version}` : ""})`;
+	return [...(config.libraries ?? []).map((library) => {
+		if (!library.dir) return `${name(library)}: a dependency, but not installed`;
+		const count = model.components.filter((c) => c.library === library.package).length;
+		return `${name(library)}: ${plural(count, "component")} from its type declarations`;
+	}), ...(config.librariesOff ?? []).map((library) => `${name(library)}: ${librariesLeftOut(config, cwd)}`)];
+}
+/**
+* `export --format dtcg|design-md`: the project's tokens as a DTCG 2025.10 file or a
+* DESIGN.md, on stdout or in the `--out` file.
+*/
+async function exportTokens(configOptions, values, io) {
+	const format = values.format;
+	if (format !== "dtcg" && format !== "design-md") {
+		io.stderr(`export: pass --format dtcg or --format design-md${format === void 0 ? "" : ` (not "${format}")`}`);
+		return 2;
+	}
+	const target = await loadTarget(configOptions);
+	warnDeprecated(target.config.deprecations, "pretty", io);
+	warnDeprecated(configWarnings(target), "pretty", io);
+	if (target.workspace) {
+		const dirs = target.workspace.projects.map((p) => p.dir);
+		io.stderr(`export: ${target.workspace.root} is a monorepo root, and each project has its own tokens. Pass --root with one of them${dirs.length ? ` (${listOf(dirs)})` : ""}.`);
+		return 2;
+	}
+	const ds = await loadDesignSystem(target.config, {
+		cache: values.cache,
+		logger: silentLogger
+	});
+	if (!ds.tokens.length) {
+		io.stderr(`export: no design tokens found in ${ds.root}. \`${NAME} inspect --explain\` shows where it looked.`);
+		return 2;
+	}
+	const result = format === "dtcg" ? toDtcg(ds.tokens) : toDesignMd(ds.tokens, { name: projectName(ds.root) });
+	for (const warning of result.warnings) io.stderr(`export: ${warning}`);
+	if (values.out === void 0) {
+		io.stdout(result.text.trimEnd());
+		return 0;
+	}
+	const file = path.resolve(io.cwd, values.out);
+	await fsp.mkdir(path.dirname(file), { recursive: true });
+	await fsp.writeFile(file, result.text);
+	io.stdout(`Wrote ${plural(result.count, "token")} to ${displayPath(io.cwd, file)} (${format === "dtcg" ? "DTCG 2025.10" : "DESIGN.md"})`);
+	return 0;
+}
+/** The package name in the root's package.json, else the folder's name. */
+function projectName(root) {
+	try {
+		const pkg = JSON.parse(fs.readFileSync(path.join(root, "package.json"), "utf8"));
+		if (typeof pkg.name === "string" && pkg.name) return pkg.name;
+	} catch {}
+	return path.basename(root);
+}
 function tokenCounts(model) {
 	const counts = /* @__PURE__ */ new Map();
 	for (const t of model.tokens) counts.set(t.category, (counts.get(t.category) ?? 0) + 1);
@@ -990,8 +1141,8 @@ async function inspectWorkspace(workspace, values, io) {
 		const { model } = ds;
 		const roots = ds.roots();
 		const tokens = [...tokenCounts(model)].map(([category, n]) => `${category} ${n}`);
-		const own = project.config.configFile && project.config.configFile !== workspace.configFile ? displayPath(workspace.root, project.config.configFile) : void 0;
-		lines.push("", `${project.dir}${project.name ? ` (${project.name})` : ""}`, ...own ? [`  config     ${own}`] : [], ...project.config.detected ? [`  detected   ${project.config.detected}`] : [], `  files      ${plural(model.stats.files.components, "component file")}, ${plural(model.stats.files.tokens, "token file")}, ${plural(model.stats.files.docs, "doc")}`, `  components ${roots.length} + ${model.components.length - roots.length} parts${roots.length ? `: ${listNames(roots.map((c) => c.name))}` : ""}`, `  tokens     ${tokens.length ? tokens.join(", ") : "none"}`, ...model.warnings.length ? [`  warnings   ${model.warnings.length}: ${model.warnings[0] ?? ""}`] : []);
+		const own = project.config.configFile && project.config.configFile !== workspace.configFile ? `${displayPath(workspace.root, project.config.configFile)}${declaredBy(project.config)}` : void 0;
+		lines.push("", `${project.dir}${project.name ? ` (${project.name})` : ""}`, ...own ? [`  config     ${own}`] : [], ...project.config.detected ? [`  detected   ${project.config.detected}`] : [], ...describeLibraries(project.config, model, io.cwd).map((line) => `  library    ${line}`), `  files      ${plural(model.stats.files.components, "component file")}, ${plural(model.stats.files.tokens, "token file")}, ${plural(model.stats.files.docs, "doc")}`, `  components ${roots.length} + ${ds.components.length - roots.length} parts${roots.length ? `: ${listNames(roots.map((c) => c.name))}` : ""}`, `  tokens     ${tokens.length ? tokens.join(", ") : "none"}`, ...model.warnings.length ? [`  warnings   ${model.warnings.length}: ${model.warnings[0] ?? ""}`] : []);
 	}
 	if (!loaded.length) lines.push("", `No workspace package has a design system that zero config finds. See ${DOCS}/troubleshooting`);
 	if (workspace.others.length) lines.push("", `Without a design system (${workspace.others.length}): ${listNames(workspace.others)}`);
@@ -1013,6 +1164,10 @@ function explainWorkspace(workspace, loaded, cwd) {
 	for (const { project, ds } of loaded) lines.push("", `${project.dir}${project.name ? ` (${project.name})` : ""}`, ...explainProject(ds, cwd, "  "));
 	return lines;
 }
+/** ` (declared by @acme/ui)` after a config a design-system package declares; empty otherwise. */
+function declaredBy(config) {
+	return config.designSystemPackage ? ` (declared by ${config.designSystemPackage.name})` : "";
+}
 /** `A, B, C` up to a dozen names, then `and 40 more`. */
 function listNames(names, max = 12) {
 	const shown = names.slice(0, max).join(", ");
@@ -1022,6 +1177,10 @@ function listNames(names, max = 12) {
 * Says once what a file's old name means: on stderr, or as a workflow warning with
 * `--format github` so it shows on the run. Never on stdout otherwise, which JSON output owns.
 */
+/** What the configs read have to say: the project's, or every package's at a monorepo root. */
+function configWarnings(target) {
+	return target.workspace ? target.workspace.warnings : target.config.warnings;
+}
 function warnDeprecated(messages, format, io) {
 	for (const text of messages ?? []) if (format === "github") io.stdout(`::warning title=${NAME}::${text}`);
 	else io.stderr(text);