cascivo 0.6.2 → 0.7.1

package/dist/index.mjs

@@ -490,9 +490,35 @@ function resolvePackageManagerFlag(args) {
 	return { error: `Unknown package manager "${raw}". Use one of: pnpm, yarn, npm, bun.` };
 }
 //#endregion
+//#region src/generated/versions.ts
+/**
+* Exact published versions, baked in at build time.
+*
+* Scaffolded apps pin these rather than `"latest"`: the cascivo packages version
+* independently on 0.x, so a floating specifier can resolve a mutually incompatible set,
+* and GETTING-STARTED.md tells adopters to pin exactly. Regenerate with `pnpm regen`.
+*/
+const CASCIVO_VERSIONS = {
+	"@cascivo/react": "0.16.0",
+	"@cascivo/themes": "0.4.10",
+	"@cascivo/charts": "0.16.0",
+	"@cascivo/icons": "0.3.7",
+	"@cascivo/eslint-config": "0.2.1"
+};
+/** `@cascivo/core`'s declared `@preact/signals-react` peer range. */
+const SIGNALS_PEER = ">=3.0.0";
+//#endregion
 //#region src/commands/create.ts
-/** Version specifier used for every `@cascivo/*` dependency in generated apps. */
-const CASCIVO_DEP = "latest";
+/**
+* Exact published versions, baked in at build time by `scripts/registry/cli-versions.ts`.
+*
+* This used to be the literal `'latest'` for every cascivo dependency — the loosest
+* possible specifier on a set of independently-versioned 0.x packages, and the direct
+* opposite of GETTING-STARTED.md's "pin **exact** versions (no `^`)". A scaffold that
+* contradicts the docs on the very first file an adopter opens undermines every other rule
+* those docs state, so the pins are generated rather than hand-written.
+*/
+const V = CASCIVO_VERSIONS;
 /** Install-everything command for a package manager (`pnpm install`, `yarn`, …). */
 function installAllCommand(pm) {
 	return pm === "yarn" ? "yarn" : `${pm} install`;
@@ -510,6 +536,24 @@ function pascalCase(label) {
 	const safe = label.trim().split(/[^a-zA-Z0-9]+/).filter(Boolean).map((p) => p.charAt(0).toUpperCase() + p.slice(1)).join("") || "Section";
 	return /^[0-9]/.test(safe) ? `Section${safe}` : safe;
 }
+/**
+* Short, human-readable brand for the shell header.
+*
+* The directory name is the wrong thing to render verbatim: a dated demo directory
+* (`vercel-dashboard-2026-07-30-take2`) produced a 45-character brand in the top-left of
+* every page. Take the leading words, title-case them, and stop — a brand is a label, not a
+* slug. Bare numbers and `v2`-style segments are dropped rather than counted.
+*/
+function brandName(name) {
+	const words = name.trim().split(/[^a-zA-Z0-9]+/).filter((w) => w !== "" && !/^\d+$/.test(w) && !/^v\d+$/i.test(w));
+	const kept = [];
+	for (const word of words) {
+		if (kept.length >= 3) break;
+		if (kept.length > 0 && kept.join(" ").length + 1 + word.length > 24) break;
+		kept.push(word.charAt(0).toUpperCase() + word.slice(1));
+	}
+	return kept.join(" ") || "App";
+}
 /** Normalize the project name into a valid npm package name. */
 function packageName(name) {
 	return name.trim().toLowerCase().replace(/[^a-z0-9._-]+/g, "-").replace(/^-+|-+$/g, "") || "cascivo-app";
@@ -553,20 +597,25 @@ function packageJson(opts) {
 		scripts: {
 			dev: "vite",
 			build: "tsc && vite build",
-			preview: "vite preview"
+			preview: "vite preview",
+			typecheck: "tsc --noEmit",
+			lint: "eslint ."
 		},
 		dependencies: {
-			"@cascivo/core": CASCIVO_DEP,
-			"@cascivo/react": CASCIVO_DEP,
-			"@cascivo/themes": CASCIVO_DEP,
-			"@cascivo/tokens": CASCIVO_DEP,
+			"@cascivo/react": V["@cascivo/react"],
+			"@cascivo/themes": V["@cascivo/themes"],
+			"@preact/signals-react": SIGNALS_PEER,
 			react: "^19.0.0",
 			"react-dom": "^19.0.0"
 		},
 		devDependencies: {
+			"@cascivo/eslint-config": V["@cascivo/eslint-config"],
+			"@eslint/js": "^9.0.0",
 			"@types/react": "^19.0.0",
 			"@types/react-dom": "^19.0.0",
 			"@vitejs/plugin-react": "^5.0.0",
+			eslint: "^9.0.0",
+			"eslint-plugin-react-hooks": "^7.0.0",
 			typescript: "^5.7.0",
 			vite: "^7.0.0"
 		}
@@ -617,7 +666,13 @@ function indexHtml(opts) {
     <meta name="viewport" content="width=device-width, initial-scale=1.0" />
     <title>${opts.name}</title>
     <style>
-      @layer vendor, cascivo.reset, cascivo.base, cascivo.tokens, cascivo.component, cascivo.theme, cascivo.blocks, cascivo.override;
+      @layer vendor, cascivo.reset, cascivo.base, cascivo.tokens, cascivo.component,
+        cascivo.theme, cascivo.blocks, cascivo.example, cascivo.override;
+      /* cascivo.example is this app's own slot — above the component/blocks layers so your
+         styles win, below cascivo.override which stays free for one-off hotfixes. The
+         generated AGENTS.md tells the agent to write there, and this statement is what makes
+         that legal: a layer used but never declared falls to the end of the cascade and
+         beats everything, which is the opposite of what the ordering is for. */
       /* Third-party CSS goes in the low-priority vendor layer so it can't beat cascivo:
          @import url('some-lib/styles.css') layer(vendor); — see docs/THIRD-PARTY-CSS.md */
       @layer cascivo.reset {
@@ -674,11 +729,16 @@ function appTsx(opts, sections) {
     },`).join("\n");
 	const renderedSections = sections.map((s) => `      {section.value === '${s.key}' && <${s.component} />}`).join("\n");
 	return `'use client'
-import { signal, useSignals } from '@cascivo/core'
-import { AppShell, ShellHeader, SideNav, type SideNavItem } from '@cascivo/react'
+import {
+  AppShell,
+  ShellHeader,
+  SideNav,
+  signal,
+  useSignals,
+  type SideNavItem,
+} from '@cascivo/react'
 ${sectionImports}
 
-import '@cascivo/tokens'
 import '@cascivo/themes/${opts.theme}.css'
 import '@cascivo/react/styles.css'
 
@@ -695,7 +755,7 @@ ${navItems}
 
   return (
     <AppShell
-      header={<ShellHeader brand={{ name: '${opts.name.replace(/'/g, "\\'")}' }} />}
+      header={<ShellHeader brand={{ name: '${brandName(opts.name).replace(/'/g, "\\'")}' }} />}
       nav={<SideNav items={navItems} />}
     >
 ${renderedSections}
@@ -740,16 +800,29 @@ export function ${section.component}() {
 }
 `;
 }
-function cascivoConfig(opts) {
-	return `import type { CascadeConfig } from 'cascivo'
-
-const config: CascadeConfig = {
-  registry: '${CASCIVO_HOST}/registry.json',
-  outputDir: 'src/components/ui',
-  theme: '${opts.theme}',
-}
+/**
+* ESLint flat config for the scaffold.
+*
+* `@cascivo/eslint-config` is wired in from the start because
+* `eslint-plugin-react-hooks@7`'s `recommended-latest` reports every `signal.value = next`
+* — the idiom AI-RULES.md mandates and the generated `App.tsx` below uses — as
+* `Error: This value cannot be modified`. Without this, `pnpm lint` on a freshly scaffolded
+* app errors on every piece of state it ships with.
+*/
+function eslintConfig() {
+	return `import js from '@eslint/js'
+import reactHooks from 'eslint-plugin-react-hooks'
+import cascivo from '@cascivo/eslint-config'
 
-export default config
+export default [
+  js.configs.recommended,
+  reactHooks.configs['recommended-latest'],
+  // Spread LAST — flat config is last-wins. This turns off \`react-hooks/immutability\`,
+  // which reports cascivo's signal writes (\`signal.value = next\`) as errors.
+  // See https://cascivo.com/docs/using-with-strict-eslint.md
+  ...cascivo,
+  { ignores: ['dist/**'] },
+]
 `;
 }
 function gitignore() {
@@ -807,7 +880,7 @@ This app's declared layer order (in \`index.html\`):
 
 \`\`\`css
 @layer vendor, cascivo.reset, cascivo.base, cascivo.tokens, cascivo.component,
-  cascivo.theme, cascivo.blocks, cascivo.override;
+  cascivo.theme, cascivo.blocks, cascivo.example, cascivo.override;
 \`\`\`
 
 ### Worked example — nesting, not new layers
@@ -850,8 +923,8 @@ function buildScaffold(opts) {
 			contents: indexHtml(opts)
 		},
 		{
-			path: "cascivo.config.ts",
-			contents: cascivoConfig(opts)
+			path: "eslint.config.js",
+			contents: eslintConfig()
 		},
 		{
 			path: ".gitignore",
@@ -956,20 +1029,35 @@ async function create(args, cwd = process.cwd()) {
 //#endregion
 //#region src/commands/doctor.ts
 var doctor_exports = /* @__PURE__ */ __exportAll({
+	checkDuplicateCore: () => checkDuplicateCore,
 	checkProjectDependencies: () => checkProjectDependencies,
 	checkSignalsCompat: () => checkSignalsCompat,
 	checkSsrConfig: () => checkSsrConfig,
-	isAdopterProject: () => isAdopterProject,
+	detectInstallPath: () => detectInstallPath,
 	runDoctor: () => runDoctor,
 	stripCommentsAndStrings: () => stripCommentsAndStrings
 });
-/** Runtime packages copied cascivo source needs; the last is @cascivo/core's peer. */
+/** Runtime packages **copied** cascivo source needs; the last is @cascivo/core's peer. */
 const REQUIRED_RUNTIME_DEPS = [
 	"@cascivo/core",
 	"@cascivo/tokens",
 	"@cascivo/themes",
 	"@preact/signals-react"
 ];
+/** Runtime packages a **prebuilt** (Path B) app needs. */
+const REQUIRED_PREBUILT_DEPS = [
+	"@cascivo/react",
+	"@cascivo/themes",
+	"@preact/signals-react"
+];
+/**
+* Packages a prebuilt app must NOT declare directly, with the rule each one breaks. They
+* are transitive there, and everything they export is re-exported from `@cascivo/react`.
+*/
+const FORBIDDEN_PREBUILT_DEPS = {
+	"@cascivo/core": "AI-RULES.md: never add @cascivo/core to a prebuilt-path app — it is transitive, and everything is re-exported from @cascivo/react",
+	"@cascivo/tokens": "GETTING-STARTED.md: @cascivo/tokens comes with @cascivo/themes as a direct dependency — never install it by hand"
+};
 /** Installed on demand by `cascivo add` when a component/chart declares them. */
 const ON_DEMAND_DEPS = ["@cascivo/i18n", "@cascivo/charts"];
 const CONFIG_FILES = [
@@ -977,17 +1065,74 @@ const CONFIG_FILES = [
 	"cascivo.config.js",
 	"cascivo.config.mjs"
 ];
-/** Whether cwd looks like a cascivo adopter project (has a generated config). */
-function isAdopterProject(cwd) {
-	return CONFIG_FILES.some((f) => existsSync(join(cwd, f)));
+/**
+* Infer the install path from evidence.
+*
+* This used to be `isAdopterProject()` — "does a `cascivo.config.*` exist?" — and
+* `cascivo create` wrote that config into every scaffold, including prebuilt-path ones. So
+* every scaffolded app was judged copy-paste and told to install `@cascivo/core` and
+* `@cascivo/tokens`, which the docs explicitly forbid on that path. `doctor --ci` exited 1
+* on a correctly-installed app, which made the CI gate the docs recommend
+* (`cascivo doctor --ci && cascivo audit --ai src`) red on day one.
+*
+* A config file now only contributes evidence when it points at a directory that actually
+* contains copied source, which is what it was ever meant to signal.
+*/
+function detectInstallPath(cwd) {
+	let deps = {};
+	let hasPackageJson = true;
+	try {
+		const pkg = JSON.parse(readFileSync(join(cwd, "package.json"), "utf8"));
+		deps = {
+			...pkg.dependencies,
+			...pkg.devDependencies
+		};
+	} catch {
+		hasPackageJson = false;
+	}
+	if (!hasPackageJson) return "unknown";
+	const usesPackage = deps["@cascivo/react"] !== void 0;
+	const copied = hasCopiedSource(cwd);
+	if (usesPackage && copied) return "hybrid";
+	if (usesPackage) return "prebuilt";
+	if (copied) return "copied";
+	return "unknown";
+}
+/** Whether the configured output directory holds vendored component source. */
+function hasCopiedSource(cwd) {
+	for (const dir of outputDirCandidates(cwd)) {
+		const full = join(cwd, dir);
+		if (!existsSync(full)) continue;
+		try {
+			if (readdirSync(full).some((f) => f.endsWith(".tsx"))) return true;
+		} catch {}
+	}
+	return false;
+}
+/** `outputDir` from the config if it declares one, plus the documented default. */
+function outputDirCandidates(cwd) {
+	const dirs = new Set(["src/components/ui"]);
+	for (const file of CONFIG_FILES) {
+		const full = join(cwd, file);
+		if (!existsSync(full)) continue;
+		try {
+			const declared = /outputDir\s*:\s*['"]([^'"]+)['"]/.exec(readFileSync(full, "utf8"))?.[1];
+			if (declared !== void 0) dirs.add(declared);
+		} catch {}
+	}
+	return [...dirs];
 }
 /**
-* Advisory check that the runtime dependencies copied source needs are declared
-* in the project's package.json. Turns the opaque "cannot find module
-* '@preact/signals-react'" build failure — the report's #4, where the peer was
-* invisible — into a diagnosed condition with a fix. Adopter-only (gated on a
-* cascivo.config by the caller); `@cascivo/i18n`/`@cascivo/charts` are advisory
-* since not every project uses them.
+* Check that the runtime dependencies this project's install path needs are declared in its
+* package.json — and, on the prebuilt path, that it declares none it must not.
+*
+* Turns the opaque "cannot find module '@preact/signals-react'" build failure into a
+* diagnosed condition with a fix. What it demands depends on `detectInstallPath`: requiring
+* `@cascivo/core` of a prebuilt app is not merely unhelpful, it is the opposite of what the
+* docs say, and following the advice makes a correct project wrong.
+*
+* `@cascivo/i18n`/`@cascivo/charts` stay advisory since not every project uses them, and an
+* `unknown` path emits nothing at all rather than guessing.
 */
 function checkProjectDependencies(cwd) {
 	let deps = {};
@@ -1000,13 +1145,24 @@ function checkProjectDependencies(cwd) {
 	} catch {
 		return [];
 	}
+	const path = detectInstallPath(cwd);
+	if (path === "unknown") return [];
 	const pm = detectPackageManager(cwd);
 	const findings = [];
-	for (const pkg of REQUIRED_RUNTIME_DEPS) if (deps[pkg] === void 0) findings.push({
+	const required = path === "prebuilt" ? REQUIRED_PREBUILT_DEPS : REQUIRED_RUNTIME_DEPS;
+	for (const pkg of required) if (deps[pkg] === void 0) findings.push({
 		package: pkg,
 		required: true,
-		hint: installHint(pm, [pkg])
+		hint: `detected ${path} install path — ${installHint(pm, [pkg])}`
 	});
+	if (path === "prebuilt") {
+		for (const [pkg, reason] of Object.entries(FORBIDDEN_PREBUILT_DEPS)) if (deps[pkg] !== void 0) findings.push({
+			package: pkg,
+			required: true,
+			kind: "forbidden",
+			hint: reason
+		});
+	}
 	for (const pkg of ON_DEMAND_DEPS) if (deps[pkg] === void 0) findings.push({
 		package: pkg,
 		required: false,
@@ -1014,6 +1170,29 @@ function checkProjectDependencies(cwd) {
 	});
 	return findings;
 }
+/** Packages that carry their own `@cascivo/core` dependency. */
+const CORE_DEPENDENTS = [
+	"@cascivo/react",
+	"@cascivo/charts",
+	"@cascivo/flow",
+	"@cascivo/editor"
+];
+async function checkDuplicateCore(cwd) {
+	const root = await readInstalledPackageVersion(cwd, "@cascivo/core");
+	const nested = [];
+	for (const owner of CORE_DEPENDENTS) {
+		const ownerRoot = join(cwd, "node_modules", owner);
+		if (!existsSync(ownerRoot)) continue;
+		const version = await readInstalledPackageVersion(ownerRoot, "@cascivo/core");
+		if (version !== null && version !== root) nested.push(`${owner} → ${version}`);
+	}
+	if (nested.length === 0) return null;
+	return {
+		root,
+		nested,
+		hint: "Align the @cascivo/* versions (they are released together — see breaking-changes.json) and reinstall. Two copies of @cascivo/core means two signal registries: writes through one are invisible to components subscribed through the other, with no error."
+	};
+}
 /**
 * Checks the installed `@preact/signals-react` against the installed React.
 * React 19 removed the `__SECRET_INTERNALS…` export that signals-react 2.x
@@ -2523,27 +2702,29 @@ async function run(args) {
 			} else {
 				const cwd = process.cwd();
 				const result = await runDoctor(cwd);
-				const { checkProjectDependencies, checkSignalsCompat, checkSsrConfig, isAdopterProject } = await Promise.resolve().then(() => doctor_exports);
-				const adopter = isAdopterProject(cwd);
+				const { checkDuplicateCore, checkProjectDependencies, checkSignalsCompat, checkSsrConfig, detectInstallPath } = await Promise.resolve().then(() => doctor_exports);
+				const adopter = detectInstallPath(cwd) !== "unknown";
 				const deps = adopter ? checkProjectDependencies(cwd) : [];
 				const missingRequired = deps.filter((d) => d.required);
 				const signalsCompat = adopter ? await checkSignalsCompat(cwd) : null;
 				const signalsError = signalsCompat?.severity === "error";
 				const ssrHint = adopter ? checkSsrConfig(cwd) : null;
-				if (result.passed && deps.length === 0 && signalsCompat === null && ssrHint === null) console.log("No violations found.");
+				const duplicateCore = adopter ? await checkDuplicateCore(cwd) : null;
+				if (result.passed && deps.length === 0 && signalsCompat === null && ssrHint === null && duplicateCore === null) console.log("No violations found.");
 				else {
 					for (const v of result.violations) console.error(`[${v.rule}] ${v.detail}\n  ${v.file}`);
-					for (const d of missingRequired) console.error(`[missing-dependency] ${d.package} is not in package.json — copied cascivo source needs it. Install: ${d.hint}`);
+					for (const d of missingRequired) console.error(d.kind === "forbidden" ? `[forbidden-dependency] ${d.package} must not be a direct dependency here. Remove it — ${d.hint}` : `[missing-dependency] ${d.package} is not in package.json. Install: ${d.hint}`);
 					if (signalsCompat) (signalsError ? console.error : console.log)(`[${signalsError ? "signals-incompatible" : "signals-outdated"}] ${signalsCompat.detail} Upgrade: ${signalsCompat.hint}`);
 					if (ssrHint) console.log(`[ssr-config] ${ssrHint}`);
+					if (duplicateCore) console.error(`[duplicate-core] More than one @cascivo/core is installed (root: ${duplicateCore.root ?? "none"}; ${duplicateCore.nested.join("; ")}). ` + duplicateCore.hint);
 					for (const d of deps.filter((x) => !x.required)) console.log(`[optional] ${d.package} is not installed; add it when a component or chart needs it: ${d.hint}`);
-					if (ci && (result.violations.length > 0 || missingRequired.length > 0 || signalsError)) process.exitCode = 1;
+					if (ci && (result.violations.length > 0 || missingRequired.length > 0 || signalsError || duplicateCore !== null)) process.exitCode = 1;
 				}
 			}
 			break;
 		}
 		case "audit": {
-			const { audit } = await import("./audit-Cn6HJkuo.mjs");
+			const { audit } = await import("./audit-C4ul-2Ix.mjs");
 			await audit(rest, await loadConfig());
 			break;
 		}