@twobirds/microcomponents 0.9.0 → 0.10.0

package/dist/cli/create.js

@@ -1,653 +0,0 @@
-/**
-Project scaffolding for `mc create --namespace xxx`.
-
-Pure, filesystem-free logic: given a namespace it returns the files of a complete,
-working Micro Components dev environment and their contents. The starter component's
-path is not re-derived here — it comes from {@link tagPath}, the same primitive the
-runtime autoload loader uses, so the scaffold and the runtime can never disagree about
-where a component lives.
-
-The namespace is the first segment of every component tag, so `xxx` makes `src/xxx/`
-the home of tags like `<xxx-app>` (tagPath `xxx-app` → `xxx/app`). The generated
-environment follows the three-path chain the library's own demos use: `src/` holds the
-authored sources, `build/` receives the per-file `tsc` output that the dev server
-serves through `autoload()`, and `public/` receives the bundled production site. Because
-the dev shell is the autoload base, `import.meta.url` + `tagPath('xxx-app')` resolves to
-`build/xxx/app.js` — the compiled starter.
-
-@module CLI/Project
-*/
-import { tagPath } from '../utils/resolveComponentPath.js';
-import { kebabToPascal } from '../utils/helpers.js';
-/** The starter component tag for a namespace: `xxx` → `xxx-app`. */
-function starterTag(namespace) {
-    return `${namespace}-app`;
-}
-/**
-Whether a string is a valid project namespace: 1 to 4 lowercase letters.
-
-@example
-```ts
-console.log(isValidNamespace('mc'));
-console.log(isValidNamespace('mcxyz'));
-console.log(isValidNamespace('toolong'));
-```
-@param ns - Candidate namespace.
-*/
-export function isValidNamespace(ns) {
-    return /^[a-z]{1,4}$/.test(ns);
-}
-/**
-Builds the files of a complete dev environment for a namespace.
-
-@example
-```ts
-const { namespace, files } = scaffoldProject('mc');
-console.log(namespace);
-console.log(Object.keys(files));
-```
-@param namespace - 1 to 4 lowercase letters; becomes the `src/<namespace>/` folder and
-the first segment of every component tag.
-@throws If `namespace` is not 1 to 4 lowercase letters.
-*/
-export function scaffoldProject(namespace) {
-    if (!isValidNamespace(namespace)) {
-        throw new Error(`invalid namespace "${namespace}": must be 1 to 4 lowercase letters (e.g. "mc")`);
-    }
-    const tag = starterTag(namespace);
-    const base = tagPath(tag);
-    const files = {};
-    files['package.json'] = packageJson(namespace);
-    files['tsconfig.json'] = tsconfig();
-    files['tsconfig.vc.json'] = tsconfigVc();
-    files['vite.config.ts'] = viteConfig(namespace);
-    files['.gitignore'] = gitignore();
-    files['opencode.jsonc'] = opencodeConfig();
-    files['.opencode/skills/components/SKILL.md'] = componentSkill(namespace, tag);
-    files['README.md'] = readme(namespace, tag);
-    files['src/index.html'] = prodShell(tag);
-    files['src/index-dev.html'] = devShell(namespace, tag);
-    files[`src/${base}.ts`] = appSource(namespace, tag);
-    files[`src/${base}.target.html`] = appHtml(namespace);
-    files[`src/${base}.target.css`] = appCss(tag);
-    files[`src/${namespace}/bundle.ts`] = bundle();
-    return { files, namespace };
-}
-function packageJson(namespace) {
-    return JSON.stringify({
-        name: `${namespace}-app`,
-        private: true,
-        type: 'module',
-        scripts: {
-            dev: 'vite',
-            build: 'vite build',
-            preview: 'vite preview --outDir public --port 5174',
-            typecheck: 'tsc --noEmit -p tsconfig.json && tsc --noEmit -p tsconfig.vc.json',
-        },
-        dependencies: {
-            '@twobirds/microcomponents': '^0.9.0',
-        },
-        devDependencies: {
-            vite: '^8.1.5',
-            typescript: '^6.0.3',
-            '@types/node': '^26.6.5',
-        },
-    }, null, '\t');
-}
-function tsconfig() {
-    return JSON.stringify({
-        compilerOptions: {
-            target: 'ESNext',
-            module: 'ESNext',
-            moduleResolution: 'Bundler',
-            lib: ['ESNext', 'DOM', 'DOM.Iterable'],
-            strict: true,
-            esModuleInterop: true,
-            skipLibCheck: true,
-            rootDir: 'src',
-            outDir: 'build',
-            removeComments: true,
-        },
-        include: ['src/**/*.ts'],
-    }, null, '\t');
-}
-function tsconfigVc() {
-    return JSON.stringify({
-        compilerOptions: {
-            target: 'ESNext',
-            module: 'ESNext',
-            moduleResolution: 'Bundler',
-            lib: ['ESNext', 'DOM'],
-            types: ['node'],
-            strict: true,
-            esModuleInterop: true,
-            skipLibCheck: true,
-            noEmit: true,
-        },
-        files: ['vite.config.ts'],
-    }, null, '\t');
-}
-function gitignore() {
-    return `node_modules/
-build/
-public/
-`;
-}
-function opencodeConfig() {
-    return JSON.stringify({
-        $schema: 'https://opencode.ai/config.json',
-        mcp: {
-            microcomponents: {
-                type: 'local',
-                command: ['npx', '-p', '@twobirds/microcomponents', 'microcomponents-mcp'],
-                enabled: true,
-            },
-        },
-    }, null, '\t');
-}
-function componentSkill(namespace, tag) {
-    return `---
-name: components
-description: Use when adding, editing, naming, or wiring a micro component in this project, registering a component in the bundle, choosing an event dispatch target, running dev or build, or touching build/ or public/.
----
-
-# Micro Components project
-
-Namespace \`${namespace}\`. Every tag starts with \`${namespace}-\`. Components live in \`src/${namespace}/\` and the starter is \`<${tag}>\`.
-
-## The chain
-
-\`src/\` → \`build/\` → \`public/\`
-
-- \`src/\` is the only folder to edit.
-- \`build/\` is the \`tsc\` output plus mirrored companion assets, served by the dev server. Generated.
-- \`public/\` is the production site: \`bundle.js\` with companion assets inlined, \`bundle.css\`, \`index.html\`. Generated.
-
-Never edit, rename, or delete anything under \`build/\` or \`public/\`. Change \`src/\` and rebuild.
-
-## Add a component
-
-\`\`\`sh
-npx mc new ${namespace}-name --target-html --target-css
-\`\`\`
-
-The tag must be kebab-case with at least one hyphen. \`ns-name\` becomes \`src/ns/name.ts\`: the first hyphen becomes the folder, which is the same rule the autoloader uses.
-
-Register the component so the production bundle picks it up:
-
-\`\`\`ts
-// src/${namespace}/bundle.ts
-import './name.js';
-\`\`\`
-
-A component missing from the barrel loads in dev through \`autoload()\` but is absent from \`public/bundle.js\`.
-
-## Companion assets
-
-A camelCase descriptor maps to a dotted filename and is listed in \`static assets\`:
-
-| descriptor | file | role |
-| --- | --- | --- |
-| \`css\` | \`name.css\` | document-level tokens under \`:root\` |
-| \`targetCss\` | \`name.target.css\` | styles scoped to the host tag |
-| \`shadowCss\` | \`name.shadow.css\` | styles inside the shadow root |
-| \`html\` | \`name.html\` | light-DOM template |
-| \`targetHtml\` | \`name.target.html\` | template for \`target.innerHTML\`, \`{key}\` tokens filled by \`parse()\` |
-| \`shadowHtml\` | \`name.shadow.html\` | template for \`shadowRoot.innerHTML\` |
-
-The loader fetches exactly the listed descriptors, so every entry in \`static assets\` needs its file.
-
-## Events
-
-Prefer a direct target with the default local dispatch and a typed payload:
-
-\`\`\`ts
-target.dispatchEvent(
-	new CustomEvent('${namespace}:action', { detail: { data: { id: 'x' } } })
-);
-\`\`\`
-
-Bubble up or down the tree only when the receiver cannot be named.
-
-## Verify
-
-\`\`\`sh
-pnpm typecheck
-pnpm dev
-pnpm build
-pnpm preview
-\`\`\`
-
-\`mc clean\` removes \`build/\`, \`public/\` and \`coverage/\`.
-
-## API reference
-
-The \`microcomponents\` MCP server registered in \`opencode.jsonc\` documents every export, the event system, and the concept essays. Query it instead of guessing an API.
-`;
-}
-function readme(namespace, tag) {
-    return `# ${namespace} App
-
-A Micro Components project scaffolded by \`mc create --namespace ${namespace}\`.
-
-## Install
-
-\`\`\`sh
-pnpm install
-\`\`\`
-
-## Dev
-
-\`\`\`sh
-pnpm dev
-\`\`\`
-
-The dev server runs \`tsc -w\` and serves \`build/\`, so a saved component reaches the
-browser through \`autoload()\` with no bundling. Companion \`.css\`, \`.html\` and \`.json\`
-files are mirrored into \`build/\` next to the compiled component, which is where the
-autoloader looks for them.
-
-## Build
-
-\`\`\`sh
-pnpm build
-\`\`\`
-
-\`public/\` is the production site: one minified \`bundle.js\` with every companion asset
-inlined by \`loadAssetsPlugin\`, the concatenated \`bundle.css\`, and the page shell. A
-single script tag loads it, no autoloader needed.
-
-\`\`\`sh
-pnpm preview
-\`\`\`
-
-## Type-check
-
-\`\`\`sh
-pnpm typecheck
-\`\`\`
-
-\`tsconfig.json\` compiles \`src/\` into \`build/\`; \`tsconfig.vc.json\` checks
-\`vite.config.ts\`, which lives outside \`src/\` and needs node types for its \`node:\`
-imports.
-
-## Components
-
-Components live in \`src/${namespace}/\`. The starter is \`<${tag}>\` (\`src/${namespace}/app.ts\`).
-
-Add a component with:
-
-\`\`\`sh
-npx mc new ${namespace}-name --target-html --target-css
-\`\`\`
-
-Then add its import to \`src/${namespace}/bundle.ts\` so the production bundle picks it up.
-
-\`.opencode/skills/components/SKILL.md\` carries the same rules for opencode: the
-\`src/\` → \`build/\` → \`public/\` chain, the asset descriptors, the bundle registration,
-and the event dispatch preference.
-`;
-}
-function viteConfig(namespace) {
-    return `/**
- * Dev and build config for a Micro Components project.
- *
- * The chain is \`src/\` → \`build/\` → \`public/\`:
- *
- * - \`build/\` is the \`tsc\` output: one \`.js\` per component at its own autoload path,
- *   plus the copied companion assets and the dev shell. The dev server serves it, so
- *   the page loads components on demand through \`autoload()\` and nothing is bundled.
- * - \`public/\` is the production output: one minified \`bundle.js\` with every companion
- *   asset inlined by \`loadAssetsPlugin\`, the concatenated \`bundle.css\`, and the
- *   production shell. A single script tag loads it, no autoloader needed.
- *
- * @module ViteConfig
- */
-
-import { defineConfig, type Plugin, type ResolvedConfig } from 'vite';
-import { loadAssetsPlugin } from '@twobirds/microcomponents/vite';
-import { spawn } from 'node:child_process';
-import { cp, mkdir, readdir, readFile, writeFile } from 'node:fs/promises';
-import path from 'node:path';
-
-const projectRoot = import.meta.dirname;
-const sourceRoot = path.join(projectRoot, 'src');
-const buildRoot = path.join(projectRoot, 'build');
-const publicRoot = path.join(projectRoot, 'public');
-const namespace = '${namespace}';
-
-const pageShells = new Set(['index.html', 'index-dev.html']);
-
-/**
- * Whether a served file is a companion asset that must stay raw text, rather
- * than one of the page shells Vite is allowed to transform.
- *
- * @example
- * \`\`\`ts
- * isCompanionAsset('app.target.html');
- * isCompanionAsset('index.html');
- * \`\`\`
- *
- * @param name Basename of the requested file.
- */
-function isCompanionAsset(name: string): boolean {
-	if (pageShells.has(name)) return false;
-	return name.endsWith('.css') || name.endsWith('.json') || name.endsWith('.html');
-}
-
-/**
- * Mirrors companion assets and the dev shell from \`src/\` into the served folder,
- * preserving the tree. Autoload resolves \`<ns-app>\` to \`<ns>/app.js\` relative to the
- * page shell, so the served folder needs the compiled component *and* its companion
- * files at the same relative path.
- *
- * @example
- * \`\`\`ts
- * await mirrorAssets(sourceRoot, buildRoot);
- * \`\`\`
- *
- * @param root Source root to walk.
- * @param out Folder to write into.
- * @param rel Path of the walked directory relative to \`root\`.
- */
-async function mirrorAssets(root: string, out: string, rel = ''): Promise<void> {
-	for (const entry of await readdir(path.join(root, rel), { withFileTypes: true })) {
-		const next = rel ? path.join(rel, entry.name) : entry.name;
-		if (entry.isDirectory()) {
-			await mirrorAssets(root, out, next);
-		} else if (isCompanionAsset(entry.name) || entry.name === 'index-dev.html') {
-			const dst = path.join(out, next);
-			await mkdir(path.dirname(dst), { recursive: true });
-			await cp(path.join(root, next), dst);
-		}
-	}
-}
-
-/**
- * Runs \`tsc -w\` for the lifetime of the dev server, so a saved component reaches
- * \`build/\` without a second command.
- *
- * @example
- * \`\`\`ts
- * plugins: [tscWatch()],
- * \`\`\`
- */
-function tscWatch(): Plugin {
-	let child: ReturnType<typeof spawn> | undefined;
-	return {
-		name: 'tsc-watch',
-		configResolved() {
-			child = spawn('npx', ['tsc', '-w', '-p', 'tsconfig.json'], { cwd: projectRoot, stdio: 'inherit' });
-		},
-		closeServer() {
-			child?.kill();
-		},
-	};
-}
-
-/**
- * Mirrors companion assets into \`build/\` before the dev server starts, and again on
- * every change, so the served folder stays autoload-ready.
- *
- * @example
- * \`\`\`ts
- * plugins: [syncBuild()],
- * \`\`\`
- */
-function syncBuild(): Plugin {
-	return {
-		name: 'sync-build',
-		enforce: 'pre',
-		async configureServer(server) {
-			await mirrorAssets(sourceRoot, buildRoot);
-			server.watcher.on('all', async (event, file) => {
-				if (!file.startsWith(sourceRoot) || file.endsWith('.ts')) return;
-				const rel = path.relative(sourceRoot, file);
-				if (isCompanionAsset(path.basename(file)) || file.endsWith('index-dev.html')) {
-					const dst = path.join(buildRoot, rel);
-					await mkdir(path.dirname(dst), { recursive: true });
-					await cp(file, dst);
-				}
-			});
-		},
-	};
-}
-
-/**
- * Serves companion \`.css\`, \`.html\` and \`.json\` files as raw text, ahead of the
- * Vite transform middleware. Without it a \`.html\` request returns the transformed
- * page shell and a \`.css\` request returns a JS module, so \`loadAssets()\` receives
- * markup it cannot use.
- *
- * @example
- * \`\`\`ts
- * plugins: [rawAssets(buildRoot)],
- * \`\`\`
- *
- * @param root Source root that mirrors the served tree.
- */
-function rawAssets(root: string): Plugin {
-	return {
-		name: 'raw-assets',
-		enforce: 'pre',
-		configureServer(server) {
-			server.middlewares.use(async (req, res, next) => {
-				const url = req.url?.split('?')[0];
-				if (!url) return next();
-				const file = decodeURIComponent(url);
-				const name = file.split('/').pop() ?? '';
-				if (!isCompanionAsset(name)) return next();
-				try {
-					const text = await readFile(path.join(root, file), 'utf-8');
-					res.setHeader('Content-Type', name.endsWith('.css') ? 'text/css' : 'text/plain');
-					res.end(text);
-				} catch {
-					next();
-				}
-			});
-		},
-	};
-}
-
-/**
- * Serves the autoload shell (\`index-dev.html\`) at \`/\`. Vite answers \`/\` with
- * \`index.html\`, which is the production shell referencing \`bundle.js\` — that file
- * only exists in \`public/\`, so the dev server has to redirect to the dev shell.
- *
- * @example
- * \`\`\`ts
- * plugins: [devShell()],
- * \`\`\`
- */
-function devShell(): Plugin {
-	return {
-		name: 'dev-shell',
-		enforce: 'pre',
-		configureServer(server) {
-			server.middlewares.use((req, res, next) => {
-				const url = req.url?.split('?')[0];
-				if (url !== '/' && url !== '/index.html') return next();
-				req.url = '/index-dev.html';
-				next();
-			});
-		},
-	};
-}
-
-/**
- * Concatenates the plain \`.css\` token presets under \`src/\` into \`bundle.css\`,
- * skipping the companion \`.target.css\` and \`.shadow.css\` files, which
- * \`loadAssetsPlugin\` inlines into the JS bundle.
- *
- * @example
- * \`\`\`ts
- * plugins: [bundleCss()],
- * \`\`\`
- */
-function bundleCss(): Plugin {
-	let outDir = '';
-	return {
-		name: 'bundle-css',
-		apply: 'build',
-		configResolved(config: ResolvedConfig) {
-			outDir = path.resolve(config.root, config.build.outDir);
-		},
-		async closeBundle() {
-			async function collect(dir: string, rel: string, found: string[]): Promise<void> {
-				for (const entry of await readdir(path.join(dir, rel), { withFileTypes: true })) {
-					const next = rel ? path.join(rel, entry.name) : entry.name;
-					if (entry.isDirectory()) {
-						await collect(path.join(dir, rel), next, found);
-					} else if (entry.name.endsWith('.css') && !/\\.(target|shadow)\\.css$/.test(entry.name)) {
-						found.push(path.join(dir, next));
-					}
-				}
-			}
-			const files: string[] = [];
-			await collect(sourceRoot, '', files);
-			const parts = await Promise.all(files.map((f) => readFile(f, 'utf-8')));
-			await mkdir(outDir, { recursive: true });
-			await writeFile(path.join(outDir, 'bundle.css'), parts.join('\\n'), 'utf-8');
-		},
-	};
-}
-
-/**
- * Copies the production shell into \`public/\` next to the bundle, so the served
- * folder is a complete static site.
- *
- * @example
- * \`\`\`ts
- * plugins: [copyShell()],
- * \`\`\`
- */
-function copyShell(): Plugin {
-	let outDir = '';
-	return {
-		name: 'copy-shell',
-		apply: 'build',
-		configResolved(config: ResolvedConfig) {
-			outDir = path.resolve(config.root, config.build.outDir);
-		},
-		async closeBundle() {
-			await cp(path.join(sourceRoot, 'index.html'), path.join(outDir, 'index.html'));
-		},
-	};
-}
-
-export default defineConfig(({ command }) => {
-	if (command === 'serve') {
-		return {
-			root: buildRoot,
-			server: { port: 5173, open: false },
-			plugins: [syncBuild(), tscWatch(), rawAssets(buildRoot), devShell()],
-		};
-	}
-	return {
-		root: sourceRoot,
-		build: {
-			outDir: publicRoot,
-			emptyOutDir: true,
-			minify: true,
-			target: 'esnext',
-			sourcemap: false,
-			lib: {
-				entry: path.join(sourceRoot, namespace, 'bundle.ts'),
-				formats: ['es'],
-				fileName: () => 'bundle.js',
-			},
-			rollupOptions: {
-				treeshake: false,
-				output: { comments: false, keepNames: true },
-			},
-		},
-		plugins: [loadAssetsPlugin(sourceRoot), bundleCss(), copyShell()],
-	};
-});
-`;
-}
-function prodShell(tag) {
-    return `<!doctype html>
-<html lang="en">
-	<head>
-		<meta charset="UTF-8" />
-		<meta name="viewport" content="width=device-width, initial-scale=1.0" />
-		<title>${tag.replace('-app', ' App')}</title>
-		<script type="module" src="bundle.js"></script>
-		<link rel="stylesheet" href="./bundle.css" />
-	</head>
-	<body>
-		<${tag}></${tag}>
-	</body>
-</html>
-`;
-}
-function devShell(namespace, tag) {
-    return `<!doctype html>
-<html lang="en">
-	<head>
-		<meta charset="UTF-8" />
-		<meta name="viewport" content="width=device-width, initial-scale=1.0" />
-		<title>${namespace} App</title>
-		<script type="module">
-			import * as m from '@twobirds/microcomponents';
-			m.autoload(true);
-			Object.assign(window, m);
-		</script>
-	</head>
-	<body>
-		<${tag}></${tag}>
-	</body>
-</html>
-`;
-}
-function bundle() {
-    return `// Barrel entry for the production bundle: imports every component so the bundler
-// registers them all in one file. Add a line here when a component is created.
-
-import './app.js';
-`;
-}
-function appSource(namespace, tag) {
-    const className = kebabToPascal(tag);
-    return `import { DC, defineCE, parse, processAssets, type McEvent } from '@twobirds/microcomponents';
-
-/**
-\`${tag}\` — the starter micro component.
-
-@example
-\`\`\`html
-<${tag}></${tag}>
-\`\`\`
-*/
-class ${className} extends DC {
-	static assets = ['targetHtml', 'targetCss'];
-
-	data = { title: 'Micro Components' };
-
-	// Fill the template \`{key}\` tokens once, instead of binding reactive state.
-	oneAssets(ev: McEvent<Record<string, string>>): void {
-		processAssets(this, {
-			targetHtml: parse(ev.detail.data.targetHtml, this.data),
-		});
-	}
-}
-
-defineCE('${tag}', ${className});
-`;
-}
-function appHtml(namespace) {
-    return `<div class="app">
-	<h1>{title}</h1>
-	<p>Namespace scaffold ready. Edit <code>src/${namespace}/app.ts</code>.</p>
-</div>
-`;
-}
-function appCss(tag) {
-    return `${tag} {
-	display: block;
-	padding: 2rem;
-	font-family: system-ui, sans-serif;
-}
-`;
-}