cascivo 0.1.4 → 0.2.0

package/dist/index.mjs

@@ -1,70 +1,16 @@
 #!/usr/bin/env node
+import { a as loadConfig, i as installCommand, o as __exportAll, r as detectPackageManager, t as DEFAULT_CONFIG } from "./config-CsnCR5eh.mjs";
+import { n as resolveOutputPath, r as writeFileSafe, t as readFileSafe } from "./fs-m7ZvuBBm.mjs";
 import { t as fetchJson } from "./http-CLkdTpxD.mjs";
 import { argv, stdin, stdout } from "node:process";
 import { pathToFileURL } from "node:url";
+import { basename, dirname, join, resolve } from "node:path";
 import { spawnSync } from "node:child_process";
 import { existsSync, readFileSync, readdirSync, writeFileSync } from "node:fs";
-import { basename, dirname, join, resolve } from "node:path";
-import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { readFile, writeFile } from "node:fs/promises";
 import { createHash } from "node:crypto";
+import { asTemplateMeta, buildRegistry, isTemplateItem, parseLegacyRegistry, validateIndex, validateTemplate } from "@cascivo/registry";
 import { createInterface } from "node:readline/promises";
-import { buildRegistry, parseLegacyRegistry, validateIndex } from "@cascivo/registry";
-//#region src/utils/config.ts
-const DEFAULT_CONFIG = {
-	registry: "https://cascivo.com/registry.json",
-	outputDir: "src/components/ui",
-	theme: "light"
-};
-const CONFIG_FILES = [
-	"cascivo.config.ts",
-	"cascivo.config.js",
-	"cascivo.config.mjs"
-];
-/** Apply defaults over a (possibly partial) user config object. */
-function resolveConfig(partial) {
-	return {
-		...DEFAULT_CONFIG,
-		...partial
-	};
-}
-/** Let env vars override config — used by the MCP server to pass `outputDir`. */
-function applyEnvOverrides(config, env = process.env) {
-	return {
-		...config,
-		...env.CASCIVO_REGISTRY ? { registry: env.CASCIVO_REGISTRY } : {},
-		...env.CASCIVO_OUTPUT_DIR ? { outputDir: env.CASCIVO_OUTPUT_DIR } : {}
-	};
-}
-/**
-* Locate and load `cascivo.config.{ts,js,mjs}` from `cwd`. Falls back to the
-* default config when no file is found or the file cannot be loaded. Env vars
-* (`CASCIVO_REGISTRY`, `CASCIVO_OUTPUT_DIR`) take precedence.
-*/
-async function loadConfig(cwd = process.cwd()) {
-	for (const file of CONFIG_FILES) {
-		const path = join(cwd, file);
-		if (!existsSync(path)) continue;
-		try {
-			const mod = await import(pathToFileURL(path).href);
-			return applyEnvOverrides(resolveConfig(mod.default ?? mod));
-		} catch {
-			return applyEnvOverrides(resolveConfig(null));
-		}
-	}
-	return applyEnvOverrides(resolveConfig(null));
-}
-/** Detect the package manager in use from lock files, defaulting to npm. */
-function detectPackageManager(cwd = process.cwd()) {
-	if (existsSync(join(cwd, "pnpm-lock.yaml"))) return "pnpm";
-	if (existsSync(join(cwd, "yarn.lock"))) return "yarn";
-	if (existsSync(join(cwd, "bun.lockb"))) return "bun";
-	return "npm";
-}
-/** The install subcommand each package manager uses to add dependencies. */
-function installCommand(pm, packages) {
-	return [pm, [pm === "npm" ? "install" : "add", ...packages]];
-}
-//#endregion
 //#region src/utils/exec.ts
 /**
 * Install npm packages using the detected package manager, inheriting stdio so
@@ -85,25 +31,6 @@ function installPackages(packages, cwd = process.cwd()) {
 	return true;
 }
 //#endregion
-//#region src/utils/fs.ts
-/** Resolve where a component file should be written. */
-function resolveOutputPath(outputDir, component, file, cwd = process.cwd()) {
-	return join(resolve(cwd, outputDir), component, file);
-}
-/** Write a file, creating parent directories as needed. */
-async function writeFileSafe(path, content) {
-	await mkdir(dirname(path), { recursive: true });
-	await writeFile(path, content, "utf8");
-}
-/** Read a file, returning null if it does not exist. */
-async function readFileSafe(path) {
-	try {
-		return await readFile(path, "utf8");
-	} catch {
-		return null;
-	}
-}
-//#endregion
 //#region src/utils/registry.ts
 function asStringArray(value) {
 	return Array.isArray(value) ? value.filter((v) => typeof v === "string") : [];
@@ -133,6 +60,10 @@ function parseRegistry(raw) {
 		};
 		if (type !== void 0) result.type = type;
 		if (typeof c.install === "string") result.install = c.install;
+		if (Array.isArray(c.registryDependencies)) {
+			const deps = asStringArray(c.registryDependencies);
+			if (deps.length > 0) result.registryDependencies = deps;
+		}
 		return result;
 	});
 	const blocks = Array.isArray(obj.blocks) ? obj.blocks.flatMap((entry) => {
@@ -365,6 +296,12 @@ async function resolveFromDirectory(ns, fetchFn) {
 }
 //#endregion
 //#region src/commands/add.ts
+var add_exports = /* @__PURE__ */ __exportAll({
+	LAYOUT_ALIASES: () => LAYOUT_ALIASES,
+	add: () => add,
+	resolveBareClosure: () => resolveBareClosure,
+	resolveTemplateTarget: () => resolveTemplateTarget
+});
 /** Dependencies always present in a cascade project — never auto-installed. */
 const ASSUMED_DEPS = new Set(["react", "react-dom"]);
 async function fetchText$1(url) {
@@ -372,6 +309,59 @@ async function fetchText$1(url) {
 	if (!res.ok) throw new Error(`Failed to fetch ${url}: ${res.status} ${res.statusText}`);
 	return res.text();
 }
+/** Resolve where a template's own file is written — relative to the project root. */
+function resolveTemplateTarget(cwd, target) {
+	return resolve(cwd, target);
+}
+/**
+* Names from other libraries → the cascivo layout primitive that fills the same
+* role, so `cascivo add flex` installs `layout/stack`. Bare names that already
+* resolve (e.g. `stack` → `layout/stack` via suffix match) need no alias.
+*/
+const LAYOUT_ALIASES = {
+	flex: "stack",
+	box: "stack",
+	hstack: "stack",
+	vstack: "stack",
+	gap: "spacer"
+};
+/**
+* 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
+* install order plus the names that could not be found. Pure — no I/O.
+*/
+function resolveBareClosure(registry, bareSpecs) {
+	const queue = bareSpecs.map((name) => ({
+		name,
+		requested: true
+	}));
+	const installed = /* @__PURE__ */ new Set();
+	const resolved = [];
+	const missing = [];
+	while (queue.length > 0) {
+		const { name, requested } = queue.shift();
+		const entry = findComponent(registry, LAYOUT_ALIASES[name.toLowerCase()] ?? name);
+		if (!entry) {
+			missing.push(name);
+			continue;
+		}
+		if (installed.has(entry.name)) continue;
+		installed.add(entry.name);
+		resolved.push({
+			entry,
+			requested
+		});
+		for (const dep of entry.registryDependencies ?? []) queue.push({
+			name: dep,
+			requested: false
+		});
+	}
+	return {
+		resolved,
+		missing
+	};
+}
 function isMultiRegistrySpec(name) {
 	return name.startsWith("@") || name.startsWith("http://") || name.startsWith("https://") || name.startsWith("./") || name.startsWith("/") || name.split("/").length >= 3;
 }
@@ -380,41 +370,51 @@ async function add(names, config, opts = {}) {
 		console.error("Usage: cascivo add <component...>");
 		return;
 	}
+	const cwd = opts.cwd ?? process.cwd();
 	const multiSpecs = names.filter(isMultiRegistrySpec);
 	const bareSpecs = names.filter((n) => !isMultiRegistrySpec(n));
-	let lock = await readLock() ?? createLock();
+	let lock = await readLock(cwd) ?? createLock();
 	if (multiSpecs.length > 0) {
 		const plan = await resolveClosure(multiSpecs, config, process.env, resolveFromDirectory);
 		if (opts.dryRun) {
 			console.log("Dry run — would install:");
 			for (const item of plan.items) {
-				console.log(`  ${item.spec} (${item.item.name}@${item.item.version}) from ${item.itemUrl}`);
-				for (const f of item.item.files) console.log(`    ${f.url}`);
+				const kind = isTemplateItem(item.item) ? " [template]" : "";
+				console.log(`  ${item.spec} (${item.item.name}@${item.item.version})${kind} from ${item.itemUrl}`);
+				for (const f of item.item.files) {
+					const arrow = isTemplateItem(item.item) && f.target ? ` → ${f.target}` : "";
+					console.log(`    ${f.url}${arrow}`);
+				}
+				if (item.item.registryDependencies?.length) console.log(`    components: ${item.item.registryDependencies.join(", ")}`);
 			}
 			return;
 		}
 		const isThirdParty = (itemUrl) => !itemUrl.includes("cascivo.com");
 		for (const { item, itemUrl, registryBase } of plan.items) {
 			if (isThirdParty(itemUrl)) console.log(`\nReview before use — files from non-directory registry: ${registryBase}\n` + (item.files ?? []).map((f) => `  ${f.url}`).join("\n"));
-			await installItem(item, config, lock, registryBase);
+			const fileHashes = await installItem(item, config, cwd);
 			lock = updateLockEntry(lock, item.name, {
 				registry: registryBase,
 				version: item.version,
 				installedAt: (/* @__PURE__ */ new Date()).toISOString().slice(0, 10),
-				files: {}
+				files: fileHashes
 			});
 		}
-		await writeLock(lock);
+		await writeLock(lock, cwd);
 		return;
 	}
 	const registry = await fetchRegistry(config.registry);
 	const missingDeps = /* @__PURE__ */ new Set();
-	for (const name of bareSpecs) {
-		const entry = findComponent(registry, name);
-		if (!entry) {
-			console.error(`Component "${name}" not found in registry. Run "cascivo list".`);
-			continue;
-		}
+	const registryBase = config.registry.replace(/\/registry\.json$/, "").replace(/\/r$/, "");
+	for (const spec of bareSpecs) {
+		const alias = LAYOUT_ALIASES[spec.toLowerCase()];
+		if (!alias) continue;
+		const target = findComponent(registry, alias);
+		if (target) console.log(`"${spec}" is not a cascivo component — installing ${target.name} (its ${spec} primitive).`);
+	}
+	const { resolved, missing } = resolveBareClosure(registry, bareSpecs);
+	for (const name of missing) console.error(`Component "${name}" not found in registry. Run "cascivo list".`);
+	for (const { entry, requested } of resolved) {
 		if (entry.type === "chart") {
 			const pkg = entry.install ?? "@cascivo/charts";
 			console.log(`Chart "${entry.name}" is distributed as an npm package.`);
@@ -426,35 +426,446 @@ async function add(names, config, opts = {}) {
 		const fileHashes = {};
 		for (const url of entry.files) {
 			const content = await fetchText$1(url);
-			const dest = resolveOutputPath(config.outputDir, outputName, fileName(url));
+			const dest = resolveOutputPath(config.outputDir, outputName, fileName(url), cwd);
 			await writeFileSafe(dest, content);
 			fileHashes[dest] = sha256(content);
 		}
 		for (const dep of entry.dependencies) if (!ASSUMED_DEPS.has(dep)) missingDeps.add(dep);
-		const registryBase = config.registry.replace(/\/registry\.json$/, "").replace(/\/r$/, "");
 		lock = updateLockEntry(lock, entry.name, {
 			registry: registryBase,
 			version: entry.version,
 			installedAt: (/* @__PURE__ */ new Date()).toISOString().slice(0, 10),
 			files: fileHashes
 		});
-		console.log(`Added ${entry.name} to ${config.outputDir}/${outputName}/`);
+		const suffix = requested ? "" : " (dependency)";
+		console.log(`Added ${entry.name} to ${config.outputDir}/${outputName}/${suffix}`);
 	}
 	if (missingDeps.size > 0) installPackages([...missingDeps]);
-	await writeLock(lock);
+	await writeLock(lock, cwd);
 }
-async function installItem(item, config, _lock, _registryBase) {
-	const outputName = item.name.includes("/") ? item.name.split("/").pop() : item.name;
+/**
+* Install a single resolved item, returning a map of written path → content
+* hash for the lockfile. A template writes its own files to their `target`
+* paths (relative to the project root); every other item writes its files under
+* the components output directory. A template's components are installed
+* separately as their own plan entries (via `registryDependencies`).
+*/
+async function installItem(item, config, cwd) {
+	const fileHashes = {};
 	const missingDeps = /* @__PURE__ */ new Set();
+	const template = isTemplateItem(item);
+	const outputName = item.name.includes("/") ? item.name.split("/").pop() : item.name;
 	for (const file of item.files ?? []) try {
 		const content = await fetchText$1(file.url);
-		await writeFileSafe(resolveOutputPath(config.outputDir, outputName, fileName(file.url)), content);
+		const dest = template && file.target ? resolveTemplateTarget(cwd, file.target) : resolveOutputPath(config.outputDir, outputName, fileName(file.url), cwd);
+		await writeFileSafe(dest, content);
+		fileHashes[dest] = sha256(content);
 	} catch {
 		console.warn(`  Could not fetch ${file.url}`);
 	}
 	for (const dep of item.dependencies ?? []) if (!ASSUMED_DEPS.has(dep)) missingDeps.add(dep);
 	if (missingDeps.size > 0) installPackages([...missingDeps]);
-	console.log(`Added ${item.name} to ${config.outputDir}/${outputName}/`);
+	if (template) {
+		const pages = item.files?.filter((f) => f.target).map((f) => f.target) ?? [];
+		console.log(`Installed template ${item.name} (${pages.length} files)`);
+	} else console.log(`Added ${item.name} to ${config.outputDir}/${outputName}/`);
+	return fileHashes;
+}
+//#endregion
+//#region src/commands/create.ts
+const THEMES$2 = [
+	"light",
+	"dark",
+	"warm"
+];
+/** Version specifier used for every `@cascivo/*` dependency in generated apps. */
+const CASCIVO_DEP = "latest";
+/** 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";
+}
+/** PascalCase identifier derived from a free-text label. */
+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;
+}
+/** 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";
+}
+/** Turn raw section labels into unique keyed/component-named sections. */
+function resolveSections(labels) {
+	const seenKeys = /* @__PURE__ */ new Set();
+	const seenComponents = /* @__PURE__ */ new Set();
+	const sections = [];
+	for (const label of labels) {
+		const trimmed = label.trim();
+		if (!trimmed) continue;
+		let key = slug(trimmed);
+		let component = pascalCase(trimmed);
+		let n = 2;
+		while (seenKeys.has(key) || seenComponents.has(component)) {
+			key = `${slug(trimmed)}-${n}`;
+			component = `${pascalCase(trimmed)}${n}`;
+			n++;
+		}
+		seenKeys.add(key);
+		seenComponents.add(component);
+		sections.push({
+			key,
+			label: trimmed,
+			component
+		});
+	}
+	return sections.length > 0 ? sections : [{
+		key: "home",
+		label: "Home",
+		component: "Home"
+	}];
+}
+function packageJson(opts) {
+	const pkg = {
+		name: packageName(opts.name),
+		private: true,
+		version: "0.0.0",
+		type: "module",
+		scripts: {
+			dev: "vite",
+			build: "tsc && vite build",
+			preview: "vite preview"
+		},
+		dependencies: {
+			"@cascivo/core": CASCIVO_DEP,
+			"@cascivo/react": CASCIVO_DEP,
+			"@cascivo/themes": CASCIVO_DEP,
+			"@cascivo/tokens": CASCIVO_DEP,
+			react: "^19.0.0",
+			"react-dom": "^19.0.0"
+		},
+		devDependencies: {
+			"@types/react": "^19.0.0",
+			"@types/react-dom": "^19.0.0",
+			"@vitejs/plugin-react": "^5.0.0",
+			typescript: "^5.7.0",
+			vite: "^7.0.0"
+		}
+	};
+	return JSON.stringify(pkg, null, 2) + "\n";
+}
+function tsconfig() {
+	return JSON.stringify({
+		compilerOptions: {
+			target: "ES2022",
+			useDefineForClassFields: true,
+			lib: [
+				"ES2022",
+				"DOM",
+				"DOM.Iterable"
+			],
+			module: "ESNext",
+			skipLibCheck: true,
+			moduleResolution: "bundler",
+			allowImportingTsExtensions: true,
+			resolveJsonModule: true,
+			isolatedModules: true,
+			moduleDetection: "force",
+			noEmit: true,
+			jsx: "react-jsx",
+			strict: true,
+			noUnusedLocals: true,
+			noUnusedParameters: true,
+			noFallthroughCasesInSwitch: true
+		},
+		include: ["src"]
+	}, null, 2) + "\n";
+}
+function viteConfig() {
+	return `import react from '@vitejs/plugin-react'
+import { defineConfig } from 'vite'
+
+export default defineConfig({
+  plugins: [react()],
+})
+`;
+}
+function indexHtml(opts) {
+	return `<!doctype html>
+<html lang="en" data-theme="${opts.theme}">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>${opts.name}</title>
+    <style>
+      @layer cascivo.reset, cascivo.tokens, cascivo.component, cascivo.theme;
+      @layer cascivo.reset {
+        *,
+        *::before,
+        *::after {
+          box-sizing: border-box;
+          margin: 0;
+          padding: 0;
+        }
+      }
+      html,
+      body,
+      #root {
+        height: 100%;
+      }
+    </style>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/main.tsx"><\/script>
+  </body>
+</html>
+`;
+}
+function mainTsx() {
+	return `import React from 'react'
+import ReactDOM from 'react-dom/client'
+import App from './App'
+
+const root = document.getElementById('root')
+if (root) {
+  ReactDOM.createRoot(root).render(
+    <React.StrictMode>
+      <App />
+    </React.StrictMode>,
+  )
+}
+`;
+}
+function viteEnv() {
+	return `/// <reference types="vite/client" />\n`;
+}
+function appTsx(opts, sections) {
+	const sectionImports = sections.map((s) => `import { ${s.component} } from './sections/${s.component}'`).join("\n");
+	const unionType = sections.map((s) => `'${s.key}'`).join(" | ");
+	const navItems = sections.map((s) => `    {
+      label: '${s.label.replace(/'/g, "\\'")}',
+      active: section.value === '${s.key}',
+      onClick: (e) => {
+        e.preventDefault()
+        section.value = '${s.key}'
+      },
+    },`).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'
+${sectionImports}
+
+import '@cascivo/tokens'
+import '@cascivo/themes/${opts.theme}.css'
+import '@cascivo/react/styles.css'
+
+type Section = ${unionType}
+
+const section = signal<Section>('${sections[0].key}')
+
+export default function App() {
+  useSignals()
+
+  const navItems: SideNavItem[] = [
+${navItems}
+  ]
+
+  return (
+    <AppShell
+      header={<ShellHeader brand={{ name: '${opts.name.replace(/'/g, "\\'")}' }} />}
+      nav={<SideNav items={navItems} />}
+    >
+${renderedSections}
+    </AppShell>
+  )
+}
+`;
+}
+function sectionTsx(section) {
+	return `import { Card, CardContent, CardHeader, CardTitle, Heading, Text } from '@cascivo/react'
+
+export function ${section.component}() {
+  return (
+    <div
+      style={{
+        display: 'grid',
+        gap: 'var(--cascivo-space-6)',
+        padding: 'var(--cascivo-space-6)',
+        maxWidth: '64rem',
+      }}
+    >
+      <div style={{ display: 'grid', gap: 'var(--cascivo-space-2)' }}>
+        <Heading level={1}>${section.label}</Heading>
+        <Text muted>
+          Edit <code>src/sections/${section.component}.tsx</code> to build out this page.
+        </Text>
+      </div>
+
+      <Card>
+        <CardHeader>
+          <CardTitle>Get started</CardTitle>
+        </CardHeader>
+        <CardContent>
+          <Text>
+            This page is wired into the app shell. Add components with{' '}
+            <code>npx cascivo add &lt;component&gt;</code>.
+          </Text>
+        </CardContent>
+      </Card>
+    </div>
+  )
+}
+`;
+}
+function cascivoConfig(opts) {
+	return `import type { CascadeConfig } from 'cascivo'
+
+const config: CascadeConfig = {
+  registry: 'https://cascivo.com/registry.json',
+  outputDir: 'src/components/ui',
+  theme: '${opts.theme}',
+}
+
+export default config
+`;
+}
+function gitignore() {
+	return `node_modules
+dist
+*.local
+.DS_Store
+`;
+}
+function readme(opts) {
+	return `# ${opts.name}
+
+A [cascivo](https://cascivo.com) app — Vite + React + TypeScript, pre-wired with
+the cascivo app shell, side navigation, and the \`${opts.theme}\` theme.
+
+## Develop
+
+\`\`\`sh
+npm install
+npm run dev
+\`\`\`
+
+## Structure
+
+- \`src/App.tsx\` — app shell, navigation, and section routing
+- \`src/sections/\` — one component per nav item
+
+Add more components with \`npx cascivo add <component>\`.
+`;
+}
+/** Build the full set of files for a new cascivo app. Pure — no filesystem I/O. */
+function buildScaffold(opts) {
+	const sections = resolveSections(opts.sections);
+	return [
+		{
+			path: "package.json",
+			contents: packageJson(opts)
+		},
+		{
+			path: "tsconfig.json",
+			contents: tsconfig()
+		},
+		{
+			path: "vite.config.ts",
+			contents: viteConfig()
+		},
+		{
+			path: "index.html",
+			contents: indexHtml(opts)
+		},
+		{
+			path: "cascivo.config.ts",
+			contents: cascivoConfig(opts)
+		},
+		{
+			path: ".gitignore",
+			contents: gitignore()
+		},
+		{
+			path: "README.md",
+			contents: readme(opts)
+		},
+		{
+			path: "src/main.tsx",
+			contents: mainTsx()
+		},
+		{
+			path: "src/vite-env.d.ts",
+			contents: viteEnv()
+		},
+		{
+			path: "src/App.tsx",
+			contents: appTsx(opts, sections)
+		},
+		...sections.map((s) => ({
+			path: `src/sections/${s.component}.tsx`,
+			contents: sectionTsx(s)
+		}))
+	];
+}
+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;
+}
+const DEFAULT_SECTIONS = [
+	"Dashboard",
+	"Reports",
+	"Settings"
+];
+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(args, "theme");
+	const sectionsArg = flagValue(args, "sections");
+	const rl = !yes && stdin.isTTY ? createInterface({
+		input: stdin,
+		output: stdout
+	}) : null;
+	try {
+		let name = nameArg;
+		if (!name && rl) name = (await rl.question("Project name? [my-cascivo-app]: ")).trim();
+		name = name || "my-cascivo-app";
+		let theme = (themeArg ?? "").toLowerCase();
+		if (!THEMES$2.includes(theme) && rl) theme = (await rl.question("Theme? (light/dark/warm) [light]: ")).trim().toLowerCase();
+		const resolvedTheme = THEMES$2.includes(theme) ? theme : "light";
+		let sectionsInput = sectionsArg;
+		if (!sectionsInput && rl) sectionsInput = (await rl.question(`Nav sections? (comma-separated) [${DEFAULT_SECTIONS.join(", ")}]: `)).trim();
+		const sections = (sectionsInput ?? "").split(",").map((s) => s.trim()).filter(Boolean);
+		const opts = {
+			name,
+			theme: resolvedTheme,
+			sections: sections.length > 0 ? sections : DEFAULT_SECTIONS
+		};
+		const targetDir = join(cwd, name);
+		if (existsSync(targetDir) && readdirSync(targetDir).length > 0) {
+			console.error(`Target directory "${name}" already exists and is not empty.`);
+			process.exitCode = 1;
+			return;
+		}
+		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(args, "template");
+		if (templateSpec) {
+			const { add } = await Promise.resolve().then(() => add_exports);
+			const { loadConfig } = await import("./config-CsnCR5eh.mjs").then((n) => n.n);
+			console.log(`\nInstalling template "${templateSpec}"…`);
+			await add([templateSpec], await loadConfig(), { cwd: targetDir });
+		}
+		console.log("\nNext steps:");
+		console.log(`  cd ${name}`);
+		console.log("  npm install");
+		console.log("  npm run dev");
+	} finally {
+		rl?.close();
+	}
 }
 //#endregion
 //#region src/commands/doctor.ts
@@ -716,9 +1127,30 @@ async function list(config, options = {}) {
 		return existsSync(join(process.cwd(), config.outputDir, outputName));
 	});
 	console.log(formatList(components));
+	console.log("\nTip: install any entry by its bare name — `cascivo add stack` resolves to `layout/stack`. Layout primitives (Stack, Grid, AutoGrid, Columns, Spacer, Center) replace inline-style layout; see docs/cookbooks/layout-and-spacing.md.");
 }
 //#endregion
 //#region src/commands/registry.ts
+/**
+* Validate every template item in an index: each must pass `validateTemplate`,
+* and any bare `registryDependencies` not present in the same index produce a
+* warning (they are expected to resolve from another registry at install time).
+* Returns `{ errors, warnings }`.
+*/
+function validateTemplates(index) {
+	const errors = [];
+	const warnings = [];
+	const localNames = new Set(index.items.map((i) => i.name));
+	for (const item of index.items) {
+		if (!isTemplateItem(item)) continue;
+		for (const e of validateTemplate(item)) errors.push(`template "${item.name}": ${e}`);
+		for (const dep of item.registryDependencies ?? []) if (!(dep.includes("/") || dep.startsWith("@") || dep.startsWith("http")) && !localNames.has(dep)) warnings.push(`template "${item.name}": component "${dep}" is not in this index — it must resolve from another registry at install time`);
+	}
+	return {
+		errors,
+		warnings
+	};
+}
 async function registryBuild(args) {
 	let inFile = "cascade-registry.json";
 	let outDir = "public/r";
@@ -748,6 +1180,13 @@ async function registryBuild(args) {
 		process.exitCode = 1;
 		return;
 	}
+	const templateResult = validateTemplates(index);
+	for (const w of templateResult.warnings) console.warn(`warn: ${w}`);
+	if (templateResult.errors.length > 0) {
+		for (const e of templateResult.errors) console.error(`error: ${e}`);
+		process.exitCode = 1;
+		return;
+	}
 	const outPath = resolve(outDir);
 	await buildRegistry(index, outPath);
 	console.log(`cascade registry build: wrote static output to ${outPath}`);
@@ -1220,6 +1659,40 @@ async function updateCheck(config) {
 }
 //#endregion
 //#region src/commands/view.ts
+/** Render an item's details as text. Pure, so it can be unit-tested. */
+function formatItem(item) {
+	const lines = [];
+	lines.push(`\n${item.name}  v${item.version}`);
+	lines.push(`Type: ${item.type}${item.category ? ` / ${item.category}` : ""}`);
+	lines.push(item.description);
+	if (item.author) lines.push(`Author: ${item.author}`);
+	if (item.license) lines.push(`License: ${item.license}`);
+	if (item.homepage) lines.push(`Homepage: ${item.homepage}`);
+	if (isTemplateItem(item)) try {
+		const meta = asTemplateMeta(item.meta);
+		lines.push(`\nTemplate: ${meta.intent}`);
+		lines.push(`Framework: ${meta.framework}`);
+		if (meta.demoUrl) lines.push(`Demo: ${meta.demoUrl}`);
+		if (meta.pages?.length) {
+			lines.push("Pages:");
+			for (const p of meta.pages) lines.push(`  ${p.name} → ${p.target}`);
+		}
+	} catch {}
+	if (item.changelog?.length) {
+		lines.push("\nChangelog:");
+		for (const c of item.changelog.slice(0, 5)) lines.push(`  ${c.version}: ${c.note}`);
+	}
+	if (item.files?.length) {
+		lines.push("\nFiles:");
+		for (const f of item.files) lines.push(`  ${f.url}${f.target ? ` → ${f.target}` : ""}`);
+	}
+	if (item.dependencies?.length) lines.push(`\nDependencies: ${item.dependencies.join(", ")}`);
+	if (item.registryDependencies?.length) {
+		const label = isTemplateItem(item) ? "Components" : "Registry dependencies";
+		lines.push(`${label}: ${item.registryDependencies.join(", ")}`);
+	}
+	return lines.join("\n");
+}
 async function view(args, config) {
 	const spec = args[0];
 	if (!spec) {
@@ -1231,25 +1704,7 @@ async function view(args, config) {
 	if (headers) fetchOpts.headers = headers;
 	if (params) fetchOpts.params = params;
 	const item = await fetchJson(url, fetchOpts);
-	console.log(`\n${item.name}  v${item.version}`);
-	console.log(`Type: ${item.type}${item.category ? ` / ${item.category}` : ""}`);
-	console.log(`${item.description}`);
-	if (item.author) console.log(`Author: ${item.author}`);
-	if (item.license) console.log(`License: ${item.license}`);
-	if (item.homepage) console.log(`Homepage: ${item.homepage}`);
-	if (item.changelog?.length) {
-		console.log("\nChangelog:");
-		for (const c of item.changelog.slice(0, 5)) console.log(`  ${c.version}: ${c.note}`);
-	}
-	if (item.files?.length) {
-		console.log("\nFiles:");
-		for (const f of item.files) {
-			const target = f.target ? ` → ${f.target}` : "";
-			console.log(`  ${f.url}${target}`);
-		}
-	}
-	if (item.dependencies?.length) console.log(`\nDependencies: ${item.dependencies.join(", ")}`);
-	if (item.registryDependencies?.length) console.log(`Registry dependencies: ${item.registryDependencies.join(", ")}`);
+	console.log(formatItem(item));
 }
 //#endregion
 //#region src/index.ts
@@ -1259,8 +1714,10 @@ const HELP = `cascivo ${VERSION} — the CSS-native, signal-driven, AI-first des
 Usage: cascivo <command> [options]
 
 Commands:
+  create [name]            Scaffold a new ready-to-run app (shell + nav + theme)
+                           (--template <spec>: start from a marketplace template)
   init                     Set up cascivo in the current project
-  add <component...>       Add one or more components to your project
+  add <component...>       Add components or a template to your project
   list [--installed]       List available components
   update [component]       Update installed components (--check: list outdated)
   search <query>           Search components across registries
@@ -1271,11 +1728,15 @@ Commands:
   doctor [--ci]            Check components for rule violations
   audit --ai <paths...>    Audit AI-generated code against the cascivo contract
   registry build           Build a static registry from a cascivo-registry.json file
+  template init <name>     Scaffold a new template (source + manifest + registry entry)
 
 Run "cascivo <command> --help" for details.`;
 async function run(args) {
 	const [command, ...rest] = args;
 	switch (command) {
+		case "create":
+			await create(rest);
+			break;
 		case "init":
 			await init();
 			break;
@@ -1304,7 +1765,7 @@ async function run(args) {
 			await theme(rest);
 			break;
 		case "eject": {
-			const { eject } = await import("./eject-D_mC1lsq.mjs");
+			const { eject } = await import("./eject-B92gZhLX.mjs");
 			const flag = (key) => {
 				const eq = rest.find((r) => r.startsWith(`--${key}=`));
 				if (eq) return eq.slice(key.length + 3);
@@ -1331,6 +1792,15 @@ async function run(args) {
 				process.exitCode = 1;
 			}
 			break;
+		case "template":
+			if (rest[0] === "init") {
+				const { templateInit } = await import("./template-init-DGEgatij.mjs");
+				await templateInit(rest.slice(1));
+			} else {
+				console.error(`Unknown template subcommand: ${rest[0]}`);
+				process.exitCode = 1;
+			}
+			break;
 		case "doctor": {
 			const ci = rest.includes("--ci");
 			if (rest.includes("--drift")) {
@@ -1347,7 +1817,7 @@ async function run(args) {
 			break;
 		}
 		case "audit": {
-			const { audit } = await import("./audit-AHr4MDMK.mjs");
+			const { audit } = await import("./audit-BRn4MeXD.mjs");
 			await audit(rest, await loadConfig());
 			break;
 		}