cascivo 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 urbanisierung
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,19 @@
+<!-- generated by scripts/readme/generate.ts — edit readme.body.md, not this file -->
+
+# cascivo
+
+> CLI — npx cascivo init / add / list / update
+
+[cascivo.com](https://cascivo.com) · [Docs](https://docs.cascivo.com) · [Storybook](https://storybook.cascivo.com) · [GitHub](https://github.com/urbanisierung/cascivo)
+
+CLI for scaffold and copy-paste workflows — `npx cascivo init`, `cascivo add <component>`, `cascivo audit --ai`. Detects your package manager, writes `cascivo.config.ts`, and fetches component source from `registry.json`.
+
+## Install
+
+```sh
+pnpm add cascivo
+```
+
+---
+
+[cascivo.com](https://cascivo.com) · [Docs](https://docs.cascivo.com) · [Storybook](https://storybook.cascivo.com) · [GitHub](https://github.com/urbanisierung/cascivo) · AI agents: use [`@cascivo/mcp`](https://github.com/urbanisierung/cascivo/tree/main/packages/mcp) and [`registry.json`](https://github.com/urbanisierung/cascivo/blob/main/registry.json) · MIT

package/bin/cascivo.mjs

@@ -0,0 +1,11 @@
+#!/usr/bin/env node
+// Committed launcher: the package `bin` points here so pnpm can always link the
+// command shim at install time, even before `dist/` is built. The actual CLI is
+// loaded lazily from the built output (produced earlier in the build graph).
+import { argv } from 'node:process'
+import { run } from '../dist/index.mjs'
+
+run(argv.slice(2)).catch((error) => {
+  console.error(error instanceof Error ? error.message : String(error))
+  process.exitCode = 1
+})

package/dist/audit-AHr4MDMK.mjs

@@ -0,0 +1,583 @@
+import { fileURLToPath } from "node:url";
+import { existsSync, readFileSync, readdirSync, statSync, writeFileSync } from "node:fs";
+import { dirname, extname, join } from "node:path";
+//#region src/utils/contract-pure.ts
+/** Normalize a color/size value for catalog comparison: lowercase, strip spaces. */
+function normalizeValue(value) {
+	return value.toLowerCase().replace(/\s+/g, "");
+}
+/** Pure builder — assemble a Contract from already-parsed JSON. Testable without fs. */
+function buildContract(input) {
+	const tokensByValue = /* @__PURE__ */ new Map();
+	for (const token of input.catalog.tokens) {
+		if (token.resolvedDefault == null) continue;
+		const key = normalizeValue(token.resolvedDefault);
+		const list = tokensByValue.get(key);
+		if (list) list.push(token.name);
+		else tokensByValue.set(key, [token.name]);
+	}
+	const contentNames = /* @__PURE__ */ new Set();
+	for (const c of input.context.components) if (c.intent?.content) contentNames.add(c.name);
+	const components = /* @__PURE__ */ new Map();
+	for (const entry of input.registry.components) {
+		const meta = entry.meta;
+		if (!meta?.name) continue;
+		const props = (meta.props ?? []).map((p) => ({
+			name: p.name,
+			type: p.type ?? "unknown",
+			required: p.required === true
+		}));
+		const requiredProps = props.filter((p) => p.required).map((p) => p.name);
+		components.set(meta.name, {
+			props,
+			requiredProps,
+			hasRequiredProps: requiredProps.length > 0,
+			hasContent: contentNames.has(meta.name)
+		});
+	}
+	return {
+		tokensByValue,
+		components
+	};
+}
+//#endregion
+//#region src/audit-ai/css-literals.ts
+/** Visual CSS properties whose literal values should be tokens. */
+const VISUAL_PROPS = new Set([
+	"color",
+	"background",
+	"background-color",
+	"border-color",
+	"box-shadow",
+	"border-radius",
+	"font-size",
+	"gap",
+	"padding",
+	"margin",
+	"width",
+	"height"
+]);
+/** Inline-style camelCase → kebab-case for the props we care about. */
+const INLINE_PROP_MAP = {
+	color: "color",
+	background: "background",
+	backgroundColor: "background-color",
+	borderColor: "border-color",
+	boxShadow: "box-shadow",
+	borderRadius: "border-radius",
+	fontSize: "font-size",
+	gap: "gap",
+	padding: "padding",
+	margin: "margin",
+	width: "width",
+	height: "height"
+};
+/** A literal value worth checking: hex, oklch/rgb/hsl(a), or px/rem number. */
+function isLiteralValue(value) {
+	const v = value.trim();
+	if (v.includes("var(")) return false;
+	if (/^#[0-9a-fA-F]{3,8}$/.test(v)) return true;
+	if (/^(oklch|oklab|rgb|rgba|hsl|hsla)\(/i.test(v)) return true;
+	if (/^-?\d*\.?\d+(px|rem)$/.test(v)) return true;
+	return false;
+}
+function classify(value, contract) {
+	const matches = contract.tokensByValue.get(normalizeValue(value));
+	if (!matches || matches.length === 0) return null;
+	const first = matches[0];
+	if (matches.length === 1 && first) return {
+		level: "error",
+		suggestedToken: first
+	};
+	return {
+		level: "info",
+		allMatches: matches
+	};
+}
+/**
+* Detect literal color/size values in CSS declarations and TSX inline styles
+* that exactly match a known cascade token. Heuristic, line-based — no full
+* CSS/JS parse. Values with no catalog match are NOT flagged (arbitrary brand
+* values are allowed).
+*/
+function findCssLiteralViolations(source, filename, contract) {
+	const findings = [];
+	const lines = source.split("\n");
+	const cssDecl = /(^|[;{\s])([a-z-]+)\s*:\s*([^;}{]+?)\s*(?=[;}]|$)/gi;
+	const inlineDecl = /([A-Za-z][A-Za-z]*)\s*:\s*(['"])([^'"]+)\2/g;
+	for (let i = 0; i < lines.length; i++) {
+		const line = lines[i];
+		if (line === void 0) continue;
+		const seen = /* @__PURE__ */ new Set();
+		for (const m of line.matchAll(cssDecl)) {
+			if (m[2] === void 0 || m[3] === void 0) continue;
+			const prop = m[2].toLowerCase();
+			const rawValue = m[3].trim();
+			if (!VISUAL_PROPS.has(prop)) continue;
+			if (!isLiteralValue(rawValue)) continue;
+			const cls = classify(rawValue, contract);
+			if (!cls) continue;
+			const key = `${prop}|${rawValue}`;
+			seen.add(key);
+			findings.push({
+				file: filename,
+				line: i + 1,
+				property: prop,
+				value: rawValue,
+				rule: "hardcoded-value",
+				...cls
+			});
+		}
+		for (const m of line.matchAll(inlineDecl)) {
+			if (m[1] === void 0 || m[3] === void 0) continue;
+			const prop = INLINE_PROP_MAP[m[1]];
+			if (!prop) continue;
+			const rawValue = m[3].trim();
+			if (!isLiteralValue(rawValue)) continue;
+			const key = `${prop}|${rawValue}`;
+			if (seen.has(key)) continue;
+			const cls = classify(rawValue, contract);
+			if (!cls) continue;
+			findings.push({
+				file: filename,
+				line: i + 1,
+				property: prop,
+				value: rawValue,
+				rule: "hardcoded-value",
+				...cls
+			});
+		}
+	}
+	return findings;
+}
+//#endregion
+//#region src/audit-ai/jsx-props.ts
+/** Props always allowed on any cascade component (DOM passthrough / React intrinsics). */
+const PASSTHROUGH = new Set([
+	"className",
+	"style",
+	"id",
+	"ref",
+	"key",
+	"children"
+]);
+function isPassthrough(prop) {
+	if (PASSTHROUGH.has(prop)) return true;
+	if (prop.startsWith("data-")) return true;
+	if (prop.startsWith("aria-")) return true;
+	if (/^on[A-Z]/.test(prop)) return true;
+	return false;
+}
+/** Names imported from @cascivo/react in this source. */
+function importedCascadeComponents(source) {
+	const names = /* @__PURE__ */ new Set();
+	for (const m of source.matchAll(/import\s*\{([^}]*)\}\s*from\s*['"]@cascivo\/react['"]/g)) {
+		const group = m[1];
+		if (group === void 0) continue;
+		for (const raw of group.split(",")) {
+			const name = raw.trim().split(/\s+as\s+/)[0]?.trim();
+			if (name) names.add(name);
+		}
+	}
+	return names;
+}
+function findOpeningTags(source, comp) {
+	const tags = [];
+	const re = new RegExp(`<${comp}(?=[\\s/>])`, "g");
+	for (const m of source.matchAll(re)) {
+		const start = m.index ?? 0;
+		let i = start + m[0].length;
+		let depth = 0;
+		let quote = "";
+		let attrs = "";
+		let closed = false;
+		for (; i < source.length; i++) {
+			const ch = source[i];
+			if (quote) {
+				if (ch === quote) quote = "";
+				attrs += ch;
+				continue;
+			}
+			if (ch === "\"" || ch === "'" || ch === "`") {
+				quote = ch;
+				attrs += ch;
+				continue;
+			}
+			if (ch === "{") depth++;
+			else if (ch === "}") depth--;
+			else if (ch === ">" && depth === 0) {
+				closed = true;
+				break;
+			}
+			attrs += ch;
+		}
+		if (!closed) continue;
+		const cleanAttrs = attrs.replace(/\/$/, "");
+		tags.push({
+			attrs: cleanAttrs,
+			index: start,
+			hasSpread: /\{\s*\.\.\./.test(cleanAttrs)
+		});
+	}
+	return tags;
+}
+/** Extract top-level attribute names from an opening-tag attribute string. */
+function extractAttrNames(attrs) {
+	const names = [];
+	let depth = 0;
+	let quote = "";
+	let token = "";
+	const flush = () => {
+		const name = token.trim().split("=")[0]?.trim();
+		if (name && /^[A-Za-z]/.test(name)) names.push(name);
+		token = "";
+	};
+	for (let i = 0; i < attrs.length; i++) {
+		const ch = attrs[i];
+		if (ch === void 0) continue;
+		if (quote) {
+			if (ch === quote) quote = "";
+			continue;
+		}
+		if (ch === "\"" || ch === "'" || ch === "`") {
+			quote = ch;
+			continue;
+		}
+		if (ch === "{") {
+			depth++;
+			continue;
+		}
+		if (ch === "}") {
+			depth--;
+			continue;
+		}
+		if (depth > 0) continue;
+		if (ch === "=") {
+			flush();
+			token = "";
+			continue;
+		}
+		if (/\s/.test(ch)) {
+			if (token.trim()) flush();
+			continue;
+		}
+		token += ch;
+	}
+	if (token.trim()) flush();
+	return names;
+}
+function lineOf(source, index) {
+	let line = 1;
+	for (let i = 0; i < index && i < source.length; i++) if (source[i] === "\n") line++;
+	return line;
+}
+/**
+* Check JSX usages of imported cascade components for unknown props.
+* Heuristic — regex/brace-aware scan, not a full AST. Elements using a spread
+* (`{...rest}`) are reported as info and skipped (props can't be statically known).
+*/
+function findJsxPropViolations(source, filename, contract) {
+	const findings = [];
+	const tracked = importedCascadeComponents(source);
+	for (const comp of tracked) {
+		const info = contract.components.get(comp);
+		if (!info) continue;
+		const known = new Set(info.props.map((p) => p.name));
+		for (const tag of findOpeningTags(source, comp)) {
+			const line = lineOf(source, tag.index);
+			if (tag.hasSpread) {
+				findings.push({
+					file: filename,
+					line,
+					component: comp,
+					prop: "...",
+					level: "info",
+					rule: "spread-suppressed",
+					message: `<${comp}> uses a spread — prop checks skipped`
+				});
+				continue;
+			}
+			for (const name of extractAttrNames(tag.attrs)) {
+				if (isPassthrough(name)) continue;
+				if (known.has(name)) continue;
+				findings.push({
+					file: filename,
+					line,
+					component: comp,
+					prop: name,
+					level: "error",
+					rule: "unknown-prop",
+					message: `<${comp}> has unknown prop "${name}"`
+				});
+			}
+		}
+	}
+	return findings;
+}
+//#endregion
+//#region src/audit-ai/raw-strings.ts
+/** Looks like English prose worth flagging: ≥2 whitespace-separated words, letters/spaces only. */
+function looksLikeProse(text) {
+	const trimmed = text.trim();
+	if (!/^[A-Za-z][A-Za-z\s]*$/.test(trimmed)) return false;
+	return trimmed.split(/\s+/).length >= 2;
+}
+/**
+* Conservative raw-string check: for cascade components that own user-facing
+* chrome text (intent.content), warn when a literal multi-word English child
+* appears, suggesting the labels prop / i18n. Never errors. Only inspects the
+* immediate text directly after the opening tag (no nested element traversal).
+*/
+function findRawStringViolations(source, filename, contract) {
+	const findings = [];
+	const tracked = importedCascadeComponents(source);
+	for (const comp of tracked) {
+		if (!contract.components.get(comp)?.hasContent) continue;
+		for (const tag of findOpeningTags(source, comp)) {
+			const openEnd = source.indexOf(">", tag.index);
+			if (openEnd === -1) continue;
+			if (source[openEnd - 1] === "/") continue;
+			const after = source.slice(openEnd + 1);
+			const stop = after.search(/[<{]/);
+			const child = (stop === -1 ? after : after.slice(0, stop)).trim();
+			if (!child || !looksLikeProse(child)) continue;
+			findings.push({
+				file: filename,
+				line: lineOf(source, openEnd),
+				component: comp,
+				text: child,
+				level: "warn",
+				rule: "raw-string",
+				message: `<${comp}> raw text "${child}" — use the labels prop / i18n`
+			});
+		}
+	}
+	return findings;
+}
+//#endregion
+//#region src/audit-ai/required-props.ts
+/**
+* Flag cascade elements that omit a prop the component marks required.
+* Elements using a spread are skipped (the prop may arrive via the spread).
+*/
+function findRequiredPropViolations(source, filename, contract) {
+	const findings = [];
+	const tracked = importedCascadeComponents(source);
+	for (const comp of tracked) {
+		const info = contract.components.get(comp);
+		if (!info?.hasRequiredProps) continue;
+		for (const tag of findOpeningTags(source, comp)) {
+			if (tag.hasSpread) continue;
+			const present = new Set(extractAttrNames(tag.attrs));
+			const line = lineOf(source, tag.index);
+			for (const req of info.requiredProps) {
+				if (present.has(req)) continue;
+				findings.push({
+					file: filename,
+					line,
+					component: comp,
+					prop: req,
+					level: "error",
+					rule: "missing-prop",
+					message: `<${comp}> requires "${req}"`
+				});
+			}
+		}
+	}
+	return findings;
+}
+//#endregion
+//#region src/utils/contract.ts
+const HERE = dirname(fileURLToPath(import.meta.url));
+/** Walk up from a start directory looking for the apps/docs/public dir. */
+function findDocsPublic(startDir) {
+	let dir = startDir;
+	for (let i = 0; i < 10; i++) {
+		const candidate = join(dir, "apps", "docs", "public");
+		if (existsSync(candidate)) return candidate;
+		dir = join(dir, "..");
+	}
+	return null;
+}
+/** Walk up from a start directory looking for registry.json at the repo root. */
+function findRegistry(startDir) {
+	let dir = startDir;
+	for (let i = 0; i < 10; i++) {
+		const candidate = join(dir, "registry.json");
+		if (existsSync(candidate)) return candidate;
+		dir = join(dir, "..");
+	}
+	return null;
+}
+/**
+* Load the published cascade contract from local generated artifacts:
+* - token catalog (apps/docs/public/tokens.catalog.json) → value→token map
+* - registry.json (repo root) → component prop index
+* - context bundle (apps/docs/public/context.json) → which components have chrome text
+*/
+async function loadContract(options) {
+	const docsPublic = findDocsPublic(HERE) ?? findDocsPublic(process.cwd());
+	const catalogPath = options?.catalogPath ?? (docsPublic ? join(docsPublic, "tokens.catalog.json") : null);
+	const contextPath = options?.contextPath ?? (docsPublic ? join(docsPublic, "context.json") : null);
+	const registryPath = options?.registryPath ?? findRegistry(HERE) ?? findRegistry(process.cwd());
+	if (!catalogPath || !existsSync(catalogPath)) throw new Error("token catalog not found (apps/docs/public/tokens.catalog.json)");
+	if (!registryPath || !existsSync(registryPath)) throw new Error("registry.json not found");
+	if (!contextPath || !existsSync(contextPath)) throw new Error("context bundle not found (apps/docs/public/context.json)");
+	return buildContract({
+		catalog: JSON.parse(readFileSync(catalogPath, "utf8")),
+		registry: JSON.parse(readFileSync(registryPath, "utf8")),
+		context: JSON.parse(readFileSync(contextPath, "utf8"))
+	});
+}
+//#endregion
+//#region src/commands/audit.ts
+const SKIP_DIRS = new Set([
+	"node_modules",
+	"dist",
+	".git",
+	"build",
+	".next",
+	"coverage"
+]);
+function collectFiles(paths) {
+	const out = [];
+	const walk = (p) => {
+		if (!existsSync(p)) return;
+		if (statSync(p).isDirectory()) {
+			const base = p.split("/").pop() ?? "";
+			if (SKIP_DIRS.has(base)) return;
+			for (const entry of readdirSync(p)) walk(join(p, entry));
+			return;
+		}
+		const ext = extname(p);
+		if (ext === ".css" || ext === ".tsx" || ext === ".ts") out.push(p);
+	};
+	for (const p of paths) walk(p);
+	return out;
+}
+function findingsFor(file, source, contract) {
+	const ext = extname(file);
+	const findings = [];
+	if (ext === ".css") findings.push(...findCssLiteralViolations(source, file, contract));
+	else if (ext === ".tsx" || ext === ".ts") {
+		findings.push(...findCssLiteralViolations(source, file, contract));
+		findings.push(...findJsxPropViolations(source, file, contract));
+		findings.push(...findRequiredPropViolations(source, file, contract));
+		findings.push(...findRawStringViolations(source, file, contract));
+	}
+	return findings;
+}
+function detail(f) {
+	switch (f.rule) {
+		case "hardcoded-value":
+			if (f.suggestedToken) return `${f.value} → var(${f.suggestedToken})`;
+			return `${f.value} → ${f.allMatches?.join(" | ") ?? "(ambiguous)"}`;
+		case "unknown-prop": return `<${f.component} ${f.prop}>`;
+		case "spread-suppressed": return `<${f.component} {...}> (props not checked)`;
+		case "missing-prop": return `<${f.component}> requires "${f.prop}"`;
+		case "raw-string": return `"${f.text}" → use labels prop / i18n`;
+	}
+}
+function levelLabel(level) {
+	return level === "warn" ? "warn" : level;
+}
+function renderFindings(findings) {
+	if (findings.length === 0) {
+		console.log("cascade audit --ai: no findings.");
+		return;
+	}
+	const rows = findings.map((f) => ({
+		loc: `${f.file}:${f.line}`,
+		level: levelLabel(f.level),
+		rule: f.rule,
+		detail: detail(f)
+	}));
+	const locW = Math.max(...rows.map((r) => r.loc.length), 8);
+	const lvlW = Math.max(...rows.map((r) => r.level.length), 5);
+	const ruleW = Math.max(...rows.map((r) => r.rule.length), 4);
+	for (const r of rows) console.log(`${r.loc.padEnd(locW)}  ${r.level.padEnd(lvlW)}  ${r.rule.padEnd(ruleW)}  ${r.detail}`);
+	console.log("---");
+	const errors = findings.filter((f) => f.level === "error").length;
+	const warnings = findings.filter((f) => f.level === "warn").length;
+	const infos = findings.filter((f) => f.level === "info").length;
+	const parts = [`${errors} error${errors === 1 ? "" : "s"}`, `${warnings} warning${warnings === 1 ? "" : "s"}`];
+	if (infos) parts.push(`${infos} info`);
+	console.log(parts.join(", "));
+}
+function escapeRe(s) {
+	return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+/**
+* Pure literal→token rewrite. Only rewrites simple `property: #hex;` style
+* declarations where exactly one token matches. Returns the new source and how
+* many findings were resolved (verified by re-running the checker).
+*/
+function fixCssLiterals(source, file, contract) {
+	const fixable = findCssLiteralViolations(source, file, contract).filter((f) => f.level === "error" && f.suggestedToken && /^#[0-9a-fA-F]{3,8}$/.test(f.value));
+	let next = source;
+	for (const f of fixable) {
+		const re = new RegExp(`(${escapeRe(f.property)}\\s*:\\s*)${escapeRe(f.value)}(\\s*[;}])`, "gi");
+		next = next.replace(re, `$1var(${f.suggestedToken})$2`);
+	}
+	if (next === source) return {
+		source,
+		fixed: 0
+	};
+	const remaining = findCssLiteralViolations(next, file, contract).filter((f) => f.level === "error" && f.suggestedToken).length;
+	return {
+		source: next,
+		fixed: fixable.length - remaining
+	};
+}
+/** Apply {@link fixCssLiterals} to each .css file on disk. */
+function applyFixes(files, contract) {
+	let fixed = 0;
+	for (const file of files) {
+		if (extname(file) !== ".css") continue;
+		const { source, fixed: n } = fixCssLiterals(readFileSync(file, "utf8"), file, contract);
+		if (n > 0) {
+			writeFileSync(file, source);
+			fixed += n;
+		}
+	}
+	return fixed;
+}
+async function audit(args, _config) {
+	if (!args.includes("--ai")) {
+		console.log("cascade audit: use --ai to audit AI-generated code against the cascade contract");
+		return;
+	}
+	const jsonOutput = args.includes("--json");
+	const fixMode = args.includes("--fix");
+	const levelIdx = args.indexOf("--level");
+	const minLevel = levelIdx >= 0 ? args[levelIdx + 1] ?? "error" : "error";
+	const paths = args.filter((a, i) => {
+		if (a.startsWith("--")) return false;
+		if (levelIdx >= 0 && i === levelIdx + 1) return false;
+		return true;
+	});
+	let contract;
+	try {
+		contract = await loadContract();
+	} catch (e) {
+		console.error(`Contract unavailable: ${e instanceof Error ? e.message : String(e)}`);
+		process.exitCode = 2;
+		return;
+	}
+	const files = collectFiles(paths.length ? paths : [process.cwd()]);
+	if (fixMode) {
+		const n = applyFixes(files, contract);
+		console.log(`cascade audit --ai --fix: rewrote ${n} literal${n === 1 ? "" : "s"} to tokens.`);
+	}
+	const allFindings = [];
+	for (const file of files) allFindings.push(...findingsFor(file, readFileSync(file, "utf8"), contract));
+	if (jsonOutput) console.log(JSON.stringify(allFindings, null, 2));
+	else renderFindings(allFindings);
+	const hasErrors = allFindings.some((f) => f.level === "error");
+	if (minLevel === "error" && hasErrors) process.exitCode = 1;
+	if (minLevel === "warn" && allFindings.some((f) => f.level !== "info")) process.exitCode = 1;
+}
+//#endregion
+export { audit };
+
+//# sourceMappingURL=audit-AHr4MDMK.mjs.map