cascivo 0.4.2 → 0.5.0

package/dist/index.mjs

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { a as detectPackageManager, c as __exportAll, n as DEFAULT_CONFIG$1, o as installCommand, r as THEMES, s as loadConfig, t as CASCIVO_HOST } from "./config-BsyJbMvD.mjs";
+import { a as detectPackageManager, c as isPackageManager, l as loadConfig, n as DEFAULT_CONFIG$1, o as installCommand, r as THEMES, s as installHint, t as CASCIVO_HOST, u as __exportAll } from "./config-CYlTGdmE.mjs";
 import { n as resolveOutputPath, r as writeFileSafe, t as readFileSafe } from "./fs-m7ZvuBBm.mjs";
 import { r as fetchTextRetry, t as fetchJson } from "./http-CJZ5W0Fa.mjs";
 import { a as updateLockEntry, c as fileName, i as sha256, l as findComponent, n as createLock, o as writeLock, r as readLock, s as fetchRegistry, t as checkPeerVersions } from "./peer-versions-B2bCgko-.mjs";
@@ -14,12 +14,16 @@ import { asTemplateMeta, buildRegistry, isTemplateItem, parseLegacyRegistry, val
 import { createInterface } from "node:readline/promises";
 //#region src/utils/exec.ts
 /**
-* Install npm packages using the detected package manager, inheriting stdio so
-* the user sees install progress. Returns false if the install failed.
+* Install npm packages using the detected (or explicitly chosen) package
+* manager, inheriting stdio so the user sees install progress. On failure it
+* prints the exact command to run by hand — the adopter can always recover even
+* when the spawn fails (e.g. npm crashing inside a pnpm workspace). Returns
+* false if the install failed.
 */
-function installPackages(packages, cwd = process.cwd()) {
+function installPackages(packages, cwd = process.cwd(), opts = {}) {
 	if (packages.length === 0) return true;
-	const [cmd, args] = installCommand(detectPackageManager(cwd), packages);
+	const pm = opts.pm ?? detectPackageManager(cwd);
+	const [cmd, args] = installCommand(pm, packages, { dev: opts.dev ?? false });
 	console.log(`Installing ${packages.join(", ")} with ${cmd}…`);
 	if (spawnSync(cmd, args, {
 		cwd,
@@ -27,6 +31,7 @@ function installPackages(packages, cwd = process.cwd()) {
 		shell: process.platform === "win32"
 	}).status !== 0) {
 		console.error(`Failed to install: ${packages.join(", ")}`);
+		console.error(`Install them yourself with: ${installHint(pm, packages, { dev: opts.dev ?? false })}`);
 		return false;
 	}
 	return true;
@@ -167,6 +172,7 @@ async function resolveFromDirectory(ns, fetchFn) {
 //#region src/commands/add.ts
 var add_exports = /* @__PURE__ */ __exportAll({
 	LAYOUT_ALIASES: () => LAYOUT_ALIASES,
+	NAME_NOTES: () => NAME_NOTES,
 	add: () => add,
 	isThirdParty: () => isThirdParty,
 	resolveBareClosure: () => resolveBareClosure,
@@ -174,23 +180,28 @@ var add_exports = /* @__PURE__ */ __exportAll({
 });
 /** Dependencies always present in a cascade project — never auto-installed. */
 const ASSUMED_DEPS = new Set(["react", "react-dom"]);
-/**
-* Copied components read `--cascivo-*` custom properties; without
-* @cascivo/tokens or @cascivo/themes imported somewhere, they render unstyled.
-* Print the wiring once after a successful install if neither is a dependency.
-*/
-function hintThemesIfMissing(cwd) {
-	let deps = {};
+/** Merged dependencies + devDependencies from the project's package.json (empty if none). */
+function readProjectDeps(cwd) {
 	try {
 		const pkg = JSON.parse(readFileSync(join(cwd, "package.json"), "utf8"));
-		deps = {
+		return {
 			...pkg.dependencies,
 			...pkg.devDependencies
 		};
-	} catch {}
+	} catch {
+		return {};
+	}
+}
+/**
+* Copied components read `--cascivo-*` custom properties; without
+* @cascivo/tokens or @cascivo/themes imported somewhere, they render unstyled.
+* Print the wiring once after a successful install if neither is a dependency.
+*/
+function hintThemesIfMissing(cwd, pm) {
+	const deps = readProjectDeps(cwd);
 	if (deps["@cascivo/themes"] !== void 0 || deps["@cascivo/tokens"] !== void 0) return;
 	console.log("\nStyling: cascivo components read --cascivo-* tokens, which this project does not import yet.");
-	console.log("  npm install @cascivo/themes");
+	console.log(`  ${installHint(pm, ["@cascivo/themes"])}`);
 	console.log("  import '@cascivo/themes/all'   // once, in your entry file");
 	console.log("  <html data-theme=\"light\">      // or any container");
 }
@@ -211,6 +222,12 @@ const LAYOUT_ALIASES = {
 	gap: "spacer"
 };
 /**
+* Disambiguation printed when a requested bare name is a real cascivo component
+* whose meaning differs from the same name elsewhere, so an adopter who grabbed
+* it by name alone learns the right primitive. Keyed by lowercased bare name.
+*/
+const NAME_NOTES = { stack: "Note: cascivo's Stack overlaps children into a card-pile (z-axis), not a vertical spacing layout. For vertical spacing use Flex direction=\"vertical\" (cascivo add flex; aliases: vstack, hstack)." };
+/**
 * Resolve the transitive closure of bare-name registry entries, following each
 * entry's `registryDependencies`. De-duped by resolved registry name and
 * cycle-safe (an entry is processed at most once). Returns resolved entries in
@@ -264,6 +281,7 @@ async function add(names, config, opts = {}) {
 		return;
 	}
 	const cwd = opts.cwd ?? process.cwd();
+	const pm = opts.pm ?? detectPackageManager(cwd);
 	const multiSpecs = names.filter(isMultiRegistrySpec);
 	let bareSpecs = names.filter((n) => !isMultiRegistrySpec(n));
 	let registry = null;
@@ -296,7 +314,10 @@ async function add(names, config, opts = {}) {
 			if (isThirdParty(itemUrl)) console.log(`\nReview before use — files from non-directory registry: ${registryBase}\n` + (item.files ?? []).map((f) => `  ${f.url}`).join("\n"));
 			let fileHashes;
 			try {
-				fileHashes = await installItem(item, config, cwd);
+				fileHashes = await installItem(item, config, cwd, {
+					pm,
+					...opts.noInstall ? { noInstall: true } : {}
+				});
 			} catch (e) {
 				console.error(`Failed to install ${item.name}: ${e instanceof Error ? e.message : e}`);
 				process.exitCode = 1;
@@ -311,7 +332,7 @@ async function add(names, config, opts = {}) {
 		}
 		await writeLock(lock, cwd);
 		if (bareSpecs.length === 0) {
-			hintThemesIfMissing(cwd);
+			hintThemesIfMissing(cwd, pm);
 			return;
 		}
 	}
@@ -320,6 +341,8 @@ async function add(names, config, opts = {}) {
 	const missingDeps = /* @__PURE__ */ new Set();
 	const registryBase = config.registry.replace(/\/registry\.json$/, "").replace(/\/r$/, "");
 	for (const spec of bareSpecs) {
+		const note = NAME_NOTES[spec.toLowerCase()];
+		if (note) console.log(note);
 		const alias = LAYOUT_ALIASES[spec.toLowerCase()];
 		if (!alias) continue;
 		const target = findComponent(registry, alias);
@@ -329,13 +352,15 @@ async function add(names, config, opts = {}) {
 	for (const name of missing) console.error(`Component "${name}" not found in registry. Run "cascivo list".`);
 	const peerFloors = {};
 	for (const { entry } of resolved) for (const [pkg, floor] of Object.entries(entry.peerVersions ?? {})) peerFloors[pkg] = floor;
+	const npmPackages = /* @__PURE__ */ new Set();
+	const importLines = [];
 	for (const { entry, requested } of resolved) {
 		if (entry.install) {
 			const pkg = entry.install;
-			console.log(`"${entry.name}" is distributed as the npm package ${pkg}.`);
-			console.log(`Install it with: npm install ${pkg}`);
-			console.log(`Then import: import { ${entry.meta.name} } from '${pkg}'`);
-			if (entry.styles) console.log(`And import its stylesheet once: import '${entry.styles}'`);
+			npmPackages.add(pkg);
+			console.log(`"${entry.name}" is distributed as the npm package ${pkg} — a runtime dependency, not copied source (updates come via your package manager).`);
+			importLines.push(`  import { ${entry.meta.name} } from '${pkg}'`);
+			if (entry.styles) importLines.push(`  import '${entry.styles}'   // once, in your entry file`);
 			continue;
 		}
 		const outputName = entry.name.includes("/") ? entry.name.split("/").pop() : entry.name;
@@ -366,16 +391,27 @@ async function add(names, config, opts = {}) {
 		const suffix = requested ? "" : " (dependency)";
 		console.log(`Added ${entry.name} to ${config.outputDir}/${outputName}/${suffix}`);
 	}
-	if (missingDeps.size > 0) installPackages([...missingDeps]);
+	if (npmPackages.size > 0) {
+		const deps = readProjectDeps(cwd);
+		const needed = [...npmPackages].filter((p) => deps[p] === void 0);
+		if (opts.dryRun) console.log(`Dry run — would install npm package(s): ${[...npmPackages].join(", ")}`);
+		else if (needed.length > 0) {
+			if (opts.noInstall) console.log(`\nSkipped install (--no-install). Install with:\n  ${installHint(pm, needed)}`);
+			else if (!installPackages(needed, cwd, { pm })) process.exitCode = 1;
+		}
+		if (importLines.length > 0) console.log(`\nImport it:\n${importLines.join("\n")}`);
+	}
+	if (missingDeps.size > 0 && !opts.dryRun) if (opts.noInstall) console.log(`\nSkipped install (--no-install). Install with:\n  ${installHint(pm, [...missingDeps])}`);
+	else installPackages([...missingDeps], cwd, { pm });
 	if (Object.keys(peerFloors).length > 0) {
 		const violations = await checkPeerVersions(cwd, peerFloors);
 		for (const v of violations) {
-			console.error(`\nWarning: ${v.pkg} ${v.installed ? `${v.installed} is` : "is not"} installed, but the copied component source needs ${v.pkg} ${v.required}. Run: npm install ${v.pkg}@latest`);
+			console.error(`\nWarning: ${v.pkg} ${v.installed ? `${v.installed} is` : "is not"} installed, but the copied component source needs ${v.pkg} ${v.required}. Run: ${installHint(pm, [`${v.pkg}@latest`])}`);
 			process.exitCode = 1;
 		}
 	}
 	await writeLock(lock, cwd);
-	hintThemesIfMissing(cwd);
+	hintThemesIfMissing(cwd, pm);
 }
 /**
 * Install a single resolved item, returning a map of written path → content
@@ -384,7 +420,7 @@ async function add(names, config, opts = {}) {
 * the components output directory. A template's components are installed
 * separately as their own plan entries (via `registryDependencies`).
 */
-async function installItem(item, config, cwd) {
+async function installItem(item, config, cwd, opts = {}) {
 	const fileHashes = {};
 	const missingDeps = /* @__PURE__ */ new Set();
 	const template = isTemplateItem(item);
@@ -399,7 +435,8 @@ async function installItem(item, config, cwd) {
 		fileHashes[dest] = sha256(content);
 	}
 	for (const dep of item.dependencies ?? []) if (!ASSUMED_DEPS.has(dep)) missingDeps.add(dep);
-	if (missingDeps.size > 0) installPackages([...missingDeps]);
+	if (missingDeps.size > 0) if (opts.noInstall) console.log(`\nSkipped install (--no-install). Install with:\n  ${installHint(opts.pm ?? detectPackageManager(cwd), [...missingDeps])}`);
+	else installPackages([...missingDeps], cwd, opts.pm ? { pm: opts.pm } : {});
 	if (template) {
 		const pages = item.files?.filter((f) => f.target).map((f) => f.target) ?? [];
 		console.log(`Installed template ${item.name} (${pages.length} files)`);
@@ -407,9 +444,62 @@ async function installItem(item, config, cwd) {
 	return fileHashes;
 }
 //#endregion
+//#region src/utils/args.ts
+/**
+* Read `--key value` or `--key=value` from an argv slice. Ignores a following
+* token that is itself a flag (so `--tokens --dry-run` yields undefined, not
+* `--dry-run`).
+*/
+function flagValue(args, key) {
+	const eq = args.find((a) => a.startsWith(`--${key}=`));
+	if (eq) return eq.slice(key.length + 3);
+	const idx = args.indexOf(`--${key}`);
+	const next = idx !== -1 ? args[idx + 1] : void 0;
+	return next && !next.startsWith("--") ? next : void 0;
+}
+/**
+* Extract positional (non-flag) arguments from an argv slice. Any token starting
+* with `-` is dropped, as is the value token immediately following a flag named
+* in `valueFlags` (e.g. `pnpm` in `--pm pnpm`), so component names never pick up
+* a flag or its value.
+*/
+function positionalArgs(args, valueFlags = []) {
+	const out = [];
+	for (let i = 0; i < args.length; i++) {
+		const token = args[i];
+		if (token.startsWith("-")) {
+			const key = token.replace(/^--?/, "").split("=")[0];
+			const next = args[i + 1];
+			if (valueFlags.includes(key) && !token.includes("=") && next !== void 0 && !next.startsWith("-")) i++;
+			continue;
+		}
+		out.push(token);
+	}
+	return out;
+}
+/**
+* Resolve the `--package-manager` / `--pm` flag to a validated PackageManager.
+* Absent flag → `{ pm: undefined }` (fall back to auto-detection). Unknown value
+* → `{ error }` so the caller can print it and exit non-zero.
+*/
+function resolvePackageManagerFlag(args) {
+	const raw = flagValue(args, "package-manager") ?? flagValue(args, "pm");
+	if (raw === void 0) return { pm: void 0 };
+	if (isPackageManager(raw)) return { pm: raw };
+	return { error: `Unknown package manager "${raw}". Use one of: pnpm, yarn, npm, bun.` };
+}
+//#endregion
 //#region src/commands/create.ts
 /** Version specifier used for every `@cascivo/*` dependency in generated apps. */
 const CASCIVO_DEP = "latest";
+/** Install-everything command for a package manager (`pnpm install`, `yarn`, …). */
+function installAllCommand(pm) {
+	return pm === "yarn" ? "yarn" : `${pm} install`;
+}
+/** Run-a-script command for a package manager (`npm run dev` vs `pnpm dev`). */
+function runScriptCommand(pm, script) {
+	return pm === "npm" ? `npm run ${script}` : `${pm} ${script}`;
+}
 /** Slug suitable for a union-member string literal: lower-kebab, alnum only. */
 function slug(label) {
 	return label.trim().toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "") || "section";
@@ -669,6 +759,7 @@ dist
 `;
 }
 function readme(opts) {
+	const pm = opts.pm ?? "npm";
 	return `# ${opts.name}
 
 A [cascivo](https://cascivo.com) app — Vite + React + TypeScript, pre-wired with
@@ -677,8 +768,8 @@ the cascivo app shell, side navigation, and the \`${opts.theme}\` theme.
 ## Develop
 
 \`\`\`sh
-npm install
-npm run dev
+${installAllCommand(pm)}
+${runScriptCommand(pm, "dev")}
 \`\`\`
 
 ## Structure
@@ -791,13 +882,6 @@ function buildScaffold(opts) {
 		}))
 	];
 }
-function flagValue$1(args, key) {
-	const eq = args.find((a) => a.startsWith(`--${key}=`));
-	if (eq) return eq.slice(key.length + 3);
-	const idx = args.indexOf(`--${key}`);
-	const next = idx !== -1 ? args[idx + 1] : void 0;
-	return next && !next.startsWith("--") ? next : void 0;
-}
 const DEFAULT_SECTIONS = [
 	"Dashboard",
 	"Reports",
@@ -805,9 +889,22 @@ const DEFAULT_SECTIONS = [
 ];
 async function create(args, cwd = process.cwd()) {
 	const yes = args.includes("--yes") || args.includes("-y");
-	const nameArg = args.find((a) => !a.startsWith("-"));
-	const themeArg = flagValue$1(args, "theme");
-	const sectionsArg = flagValue$1(args, "sections");
+	const nameArg = positionalArgs(args, [
+		"pm",
+		"package-manager",
+		"theme",
+		"sections",
+		"template"
+	])[0];
+	const themeArg = flagValue(args, "theme");
+	const sectionsArg = flagValue(args, "sections");
+	const pmFlag = resolvePackageManagerFlag(args);
+	if ("error" in pmFlag) {
+		console.error(pmFlag.error);
+		process.exitCode = 1;
+		return;
+	}
+	const pm = detectPackageManager(cwd, pmFlag.pm ? { override: pmFlag.pm } : {});
 	const rl = !yes && stdin.isTTY ? createInterface({
 		input: stdin,
 		output: stdout
@@ -825,7 +922,8 @@ async function create(args, cwd = process.cwd()) {
 		const opts = {
 			name,
 			theme: resolvedTheme,
-			sections: sections.length > 0 ? sections : DEFAULT_SECTIONS
+			sections: sections.length > 0 ? sections : DEFAULT_SECTIONS,
+			pm
 		};
 		const targetDir = join(cwd, name);
 		if (existsSync(targetDir) && readdirSync(targetDir).length > 0) {
@@ -836,23 +934,83 @@ async function create(args, cwd = process.cwd()) {
 		const files = buildScaffold(opts);
 		for (const file of files) await writeFileSafe(join(targetDir, file.path), file.contents);
 		console.log(`\nCreated ${name} with the ${resolvedTheme} theme (${files.length} files).`);
-		const templateSpec = flagValue$1(args, "template");
+		const templateSpec = flagValue(args, "template");
 		if (templateSpec) {
 			const { add } = await Promise.resolve().then(() => add_exports);
-			const { loadConfig } = await import("./config-BsyJbMvD.mjs").then((n) => n.i);
+			const { loadConfig } = await import("./config-CYlTGdmE.mjs").then((n) => n.i);
 			console.log(`\nInstalling template "${templateSpec}"…`);
-			await add([templateSpec], await loadConfig(), { cwd: targetDir });
+			await add([templateSpec], await loadConfig(), {
+				cwd: targetDir,
+				pm
+			});
 		}
 		console.log("\nNext steps:");
 		console.log(`  cd ${name}`);
-		console.log("  npm install");
-		console.log("  npm run dev");
+		console.log(`  ${installAllCommand(pm)}`);
+		console.log(`  ${runScriptCommand(pm, "dev")}`);
 	} finally {
 		rl?.close();
 	}
 }
 //#endregion
 //#region src/commands/doctor.ts
+var doctor_exports = /* @__PURE__ */ __exportAll({
+	checkProjectDependencies: () => checkProjectDependencies,
+	isAdopterProject: () => isAdopterProject,
+	runDoctor: () => runDoctor,
+	stripCommentsAndStrings: () => stripCommentsAndStrings
+});
+/** 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"
+];
+/** Installed on demand by `cascivo add` when a component/chart declares them. */
+const ON_DEMAND_DEPS = ["@cascivo/i18n", "@cascivo/charts"];
+const CONFIG_FILES = [
+	"cascivo.config.ts",
+	"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)));
+}
+/**
+* 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.
+*/
+function checkProjectDependencies(cwd) {
+	let deps = {};
+	try {
+		const pkg = JSON.parse(readFileSync(join(cwd, "package.json"), "utf8"));
+		deps = {
+			...pkg.dependencies,
+			...pkg.devDependencies
+		};
+	} catch {
+		return [];
+	}
+	const pm = detectPackageManager(cwd);
+	const findings = [];
+	for (const pkg of REQUIRED_RUNTIME_DEPS) if (deps[pkg] === void 0) findings.push({
+		package: pkg,
+		required: true,
+		hint: installHint(pm, [pkg])
+	});
+	for (const pkg of ON_DEMAND_DEPS) if (deps[pkg] === void 0) findings.push({
+		package: pkg,
+		required: false,
+		hint: installHint(pm, [pkg])
+	});
+	return findings;
+}
 const BANNED_HOOKS = [
 	"useState",
 	"useEffect",
@@ -1090,13 +1248,21 @@ async function generate(args, config) {
 }
 //#endregion
 //#region src/commands/init.ts
-function flagValue(args, key) {
-	const eq = args.find((a) => a.startsWith(`--${key}=`));
-	if (eq) return eq.slice(key.length + 3);
-	const idx = args.indexOf(`--${key}`);
-	const next = idx !== -1 ? args[idx + 1] : void 0;
-	return next && !next.startsWith("--") ? next : void 0;
-}
+/**
+* Everything an app needs to build with copied cascivo source: the runtime
+* packages plus the `@preact/signals-react` peer of `@cascivo/core` (installed
+* explicitly rather than relying on peer auto-linking, which yarn never does and
+* npm skips when its install crashes). `@cascivo/i18n`/`@cascivo/charts` are
+* added on demand by `cascivo add` when a component or chart declares them.
+*/
+const RUNTIME_DEPS = [
+	"@cascivo/core",
+	"@cascivo/tokens",
+	"@cascivo/themes",
+	"@preact/signals-react"
+];
+/** Dev-only: `cascivo` provides the `CascadeConfig` type the generated config imports. */
+const DEV_DEPS = ["cascivo"];
 async function promptTheme() {
 	const rl = createInterface({
 		input: stdin,
@@ -1121,23 +1287,73 @@ const config: CascadeConfig = {
 export default config
 `;
 }
+const ESLINT_CONFIGS = [
+	"eslint.config.js",
+	"eslint.config.mjs",
+	"eslint.config.cjs",
+	"eslint.config.ts",
+	".eslintrc",
+	".eslintrc.js",
+	".eslintrc.cjs",
+	".eslintrc.json",
+	".eslintrc.yml",
+	".eslintrc.yaml"
+];
+/**
+* Copied cascivo source can trip a strict host ESLint config on stylistic rules.
+* If the project has an ESLint config, point at the scoping recipe rather than
+* editing the adopter's config for them.
+*/
+function hintEslintIfPresent(cwd) {
+	if (!ESLINT_CONFIGS.some((f) => existsSync(join(cwd, f)))) return;
+	console.log("\nESLint: copied cascivo source may trip a strict host config on stylistic rules.");
+	console.log("  Scope them off your components dir — see docs/USING-WITH-STRICT-ESLINT.md");
+}
+/** The "here's everything you need" summary, printed once at the end of init. */
+function printDependencySummary() {
+	console.log("\nDependencies");
+	console.log(`  runtime: ${RUNTIME_DEPS.join(" ")}`);
+	console.log(`  dev:     ${DEV_DEPS.join(" ")} (types for cascivo.config.ts)`);
+	console.log("  on demand: @cascivo/i18n, @cascivo/charts — added by `cascivo add` when a component or chart needs them");
+}
 async function init(args = [], cwd = process.cwd()) {
 	const yes = args.includes("--yes") || args.includes("-y");
+	const noInstall = args.includes("--no-install");
 	const themeArg = flagValue(args, "theme")?.toLowerCase();
 	if (themeArg !== void 0 && !THEMES.includes(themeArg)) {
 		console.error(`Unknown theme "${themeArg}". Available: ${THEMES.join(", ")}`);
 		process.exitCode = 1;
 		return;
 	}
-	installPackages(["@cascivo/core", "@cascivo/tokens"], cwd);
+	const pmFlag = resolvePackageManagerFlag(args);
+	if ("error" in pmFlag) {
+		console.error(pmFlag.error);
+		process.exitCode = 1;
+		return;
+	}
+	const pm = detectPackageManager(cwd, pmFlag.pm ? { override: pmFlag.pm } : {});
 	const interactive = themeArg === void 0 && !yes && stdin.isTTY;
 	const theme = themeArg ?? (interactive ? await promptTheme() : "light");
 	await writeFileSafe(join(cwd, "cascivo.config.ts"), configFileContents(theme));
 	console.log(`\nCreated cascivo.config.ts (theme: ${theme})`);
-	console.log("Import the theme in your root CSS or entry file:");
+	if (noInstall) {
+		console.log("\nSkipped install (--no-install). Install the dependencies yourself:");
+		console.log(`  ${installHint(pm, RUNTIME_DEPS)}`);
+		console.log(`  ${installHint(pm, DEV_DEPS, { dev: true })}`);
+	} else {
+		const runtimeOk = installPackages(RUNTIME_DEPS, cwd, { pm });
+		const devOk = installPackages(DEV_DEPS, cwd, {
+			pm,
+			dev: true
+		});
+		if (!runtimeOk || !devOk) process.exitCode = 1;
+	}
+	console.log("\nImport the theme in your root CSS or entry file:");
 	console.log(`  import '@cascivo/themes/${theme}.css'`);
-	console.log(`Then set the theme on your root element:`);
+	console.log("Then set the theme on your root element:");
 	console.log(`  <html data-theme="${theme}">`);
+	printDependencySummary();
+	hintEslintIfPresent(cwd);
 	console.log("\nAdd components with: cascivo add <name>");
 }
 //#endregion
@@ -2015,18 +2231,22 @@ Scaffold a new ready-to-run app — Vite + React + TypeScript, pre-wired with th
 cascivo app shell, side navigation, header, and a theme.
 
 Options:
-  --template <spec>     Start from a marketplace template (@ns/name or owner/repo/name)
-  --theme <name>        Theme to install (${THEME_LIST})
-  --sections "<a, b>"   Comma-separated nav section labels (one component each)
-  --yes, -y             Accept defaults, never prompt`,
+  --template <spec>         Start from a marketplace template (@ns/name or owner/repo/name)
+  --theme <name>            Theme to install (${THEME_LIST})
+  --sections "<a, b>"       Comma-separated nav section labels (one component each)
+  --package-manager <pm>    Package manager for README/next-steps (alias --pm; default: auto-detect)
+  --yes, -y                 Accept defaults, never prompt`,
 	init: `Usage: cascivo init [options]
 
-Set up cascivo in the current project: installs @cascivo/core + @cascivo/tokens
-and writes cascivo.config.ts.
+Set up cascivo in the current project: writes cascivo.config.ts and installs the
+runtime dependencies (@cascivo/core, @cascivo/tokens, @cascivo/themes, the
+@preact/signals-react peer) plus cascivo as a dev dependency for the config's types.
 
 Options:
-  --theme <name>  Theme to configure (${THEME_LIST})
-  --yes, -y       Accept defaults, never prompt (implied when stdin is not a TTY)`,
+  --theme <name>            Theme to configure (${THEME_LIST})
+  --package-manager <pm>    Force pnpm | yarn | npm | bun (alias --pm; default: auto-detect)
+  --no-install              Write files only; print the install commands to run yourself
+  --yes, -y                 Accept defaults, never prompt (implied when stdin is not a TTY)`,
 	add: `Usage: cascivo add <component...> [options]
 
 Copy component source (TSX + CSS module) from the registry into your project,
@@ -2034,8 +2254,10 @@ resolving component dependencies. Also installs templates (@ns/name) and
 third-party components (owner/repo/name).
 
 Options:
-  --dry-run  Show what would be written without writing
-  --yes, -y  Skip confirmation prompts`,
+  --dry-run                 Show what would be written without writing
+  --package-manager <pm>    Force pnpm | yarn | npm | bun (alias --pm; default: auto-detect)
+  --no-install              Don't install npm-distributed entries or deps; print the commands instead
+  --yes, -y                 Skip confirmation prompts`,
 	list: `Usage: cascivo list [options]
 
 List components available in the configured registry.
@@ -2089,10 +2311,13 @@ Options:
 	doctor: `Usage: cascivo doctor [options]
 
 Check components in this repo for cascivo rule violations (banned React hooks,
-hardcoded strings, missing @cascivo/react exports).
+hardcoded strings, missing @cascivo/react exports). In an adopter project (one
+with a cascivo.config), also verifies the runtime dependencies copied source
+needs — @cascivo/core, @cascivo/tokens, @cascivo/themes, and the
+@preact/signals-react peer — are declared in package.json.
 
 Options:
-  --ci     Exit non-zero when violations are found
+  --ci     Exit non-zero when violations or missing runtime deps are found
   --drift  Compare installed components against the registry (copy-paste drift)`,
 	audit: `Usage: cascivo audit --ai <paths...> [options]
 
@@ -2138,12 +2363,21 @@ async function run(args) {
 		case "init":
 			await init(rest);
 			break;
-		case "add":
-			await add(rest, await loadConfig(), {
+		case "add": {
+			const pmFlag = resolvePackageManagerFlag(rest);
+			if ("error" in pmFlag) {
+				console.error(pmFlag.error);
+				process.exitCode = 1;
+				break;
+			}
+			await add(positionalArgs(rest, ["pm", "package-manager"]), await loadConfig(), {
 				dryRun: rest.includes("--dry-run"),
-				yes: rest.includes("--yes")
+				yes: rest.includes("--yes"),
+				noInstall: rest.includes("--no-install"),
+				...pmFlag.pm ? { pm: pmFlag.pm } : {}
 			});
 			break;
+		}
 		case "list":
 			await list(await loadConfig(), { installed: rest.includes("--installed") });
 			break;
@@ -2205,11 +2439,17 @@ async function run(args) {
 				const { runDoctorDrift } = await import("./drift-Ciw5qeEt.mjs");
 				await runDoctorDrift(await loadConfig());
 			} else {
-				const result = await runDoctor(process.cwd());
-				if (result.passed) console.log("No violations found.");
+				const cwd = process.cwd();
+				const result = await runDoctor(cwd);
+				const { checkProjectDependencies, isAdopterProject } = await Promise.resolve().then(() => doctor_exports);
+				const deps = isAdopterProject(cwd) ? checkProjectDependencies(cwd) : [];
+				const missingRequired = deps.filter((d) => d.required);
+				if (result.passed && deps.length === 0) console.log("No violations found.");
 				else {
 					for (const v of result.violations) console.error(`[${v.rule}] ${v.detail}\n  ${v.file}`);
-					if (ci) process.exitCode = 1;
+					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 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)) process.exitCode = 1;
 				}
 			}
 			break;