@webmate-studio/cli 0.3.62 → 0.4.0

package/src/commands/build.js

@@ -0,0 +1,335 @@
+/**
+ * `wm build` — local dry-run of the component build pipeline.
+ *
+ * Calls the same `buildComponent()` function the cloud build-service uses,
+ * so a local pass should produce the same artefacts as a cloud build for
+ * 95% of cases. Reports build errors with full esbuild output + a heuristic
+ * hint about the likely cause, optionally writes the produced HTML / CSS /
+ * island bundles to disk for inspection.
+ *
+ * Does NOT push, upload, or talk to the CMS. Pure local validation.
+ *
+ * Typical workflow when a `wm push` fails with a cryptic build error:
+ *   1. `wm build` in the same directory → see the full error locally
+ *   2. Fix the cause
+ *   3. `wm build` again until green
+ *   4. `wm push`
+ *
+ * The build runs in a tmp dir inside the OS temp; cleanup is automatic
+ * unless --keep is passed (debug).
+ */
+
+import { existsSync, readFileSync, writeFileSync, mkdirSync, rmSync, statSync } from 'fs';
+import { basename, resolve, join, dirname } from 'path';
+import { performance } from 'node:perf_hooks';
+import pc from 'picocolors';
+import { buildComponent } from '@webmate-studio/builder/build-service.js';
+import { readComponentFiles } from '../utils/component-files.js';
+
+const KB = 1024;
+
+function resolveComponentDir(arg) {
+	const cwd = process.cwd();
+	if (!arg) return cwd;
+	return resolve(cwd, arg);
+}
+
+/**
+ * Take the {relPath: content-or-base64-string} map produced by
+ * readComponentFiles and shape it into the `buildComponent()` payload.
+ * Mirrors the transformation in webmate-studio's component-sync-processor.js
+ * — keep those two in sync.
+ */
+function buildPayloadFromFiles(files, componentName) {
+	let componentMetadata = null;
+	let html = null;
+	let packageJson = null;
+	const islands = [];
+	const assets = [];
+
+	for (const [relPath, content] of Object.entries(files)) {
+		if (relPath === 'component.json') {
+			try {
+				componentMetadata = JSON.parse(content);
+			} catch (err) {
+				throw new Error(`component.json is not valid JSON: ${err.message}`);
+			}
+			continue;
+		}
+		if (relPath === 'component.html') {
+			html = content;
+			continue;
+		}
+		if (relPath === 'package.json') {
+			try {
+				packageJson = JSON.parse(content);
+			} catch {
+				// Non-fatal: tolerate broken package.json by passing null —
+				// build-service skips npm install when absent.
+			}
+			continue;
+		}
+
+		if (relPath.startsWith('islands/')) {
+			const fileName = relPath.slice('islands/'.length);
+			// Islands are always text — base64-encoded svelte/js files
+			// wouldn't make sense. Strip the prefix defensively.
+			const text = content.startsWith('base64:')
+				? Buffer.from(content.slice(7), 'base64').toString('utf-8')
+				: content;
+			islands.push({ file: fileName, content: text });
+			continue;
+		}
+
+		if (relPath.startsWith('assets/')) {
+			const fileName = relPath.slice('assets/'.length);
+			if (content.startsWith('base64:')) {
+				assets.push({ file: fileName, content: content.slice(7), encoding: 'base64' });
+			} else {
+				assets.push({ file: fileName, content, encoding: 'utf-8' });
+			}
+			continue;
+		}
+
+		// Everything else (README, .webmate.json, etc.) is intentionally
+		// excluded from the build payload — neither the build-service nor
+		// the runtime cares about it.
+	}
+
+	if (!componentMetadata) {
+		throw new Error('component.json is missing — required for building');
+	}
+	if (!componentMetadata.id) {
+		throw new Error('component.json is missing the "id" field — required (UUID)');
+	}
+
+	return {
+		componentName,
+		packageJson,
+		islands,
+		assets,
+		html,
+		componentMetadata
+	};
+}
+
+/**
+ * Try to recognise common build failures and append a short hint about the
+ * most likely cause. Returns null when nothing applies — we never emit a
+ * misleading guess.
+ */
+function diagnoseError(message) {
+	if (!message) return null;
+	const m = String(message);
+
+	if (/Tag name must be lowercase and hyphenated/i.test(m)) {
+		return [
+			'Likely cause: a Svelte island in a subfolder (islands/Foo/Bar.svelte)',
+			'produced an invalid custom-element tag. The build-service should',
+			'strip the directory prefix; this was fixed in @webmate-studio/builder',
+			'>= 0.2.185. Run `npm ls -g @webmate-studio/cli` to check the version.'
+		].join('\n  ');
+	}
+
+	if (/ENOENT.*islands\/.+\//i.test(m)) {
+		return [
+			'Likely cause: an island file in a subfolder failed to write because',
+			'the parent directory was not created first. Fixed in',
+			'@webmate-studio/builder >= 0.2.185 (mkdir parent dirs).'
+		].join('\n  ');
+	}
+
+	if (/Could not resolve "([^"]+)"/i.test(m)) {
+		const match = m.match(/Could not resolve "([^"]+)"/i);
+		const dep = match?.[1];
+		return [
+			`Likely cause: missing dependency "${dep}". Add it to the component's`,
+			'package.json so the build-service installs it in the build sandbox.'
+		].join('\n  ');
+	}
+
+	if (/Unexpected token|Expected/i.test(m) && /esbuild|svelte/i.test(m)) {
+		return 'Likely cause: syntax error in island source. The location/line is shown above.';
+	}
+
+	if (/customElement.*invalid|svelte_options_invalid/i.test(m)) {
+		return 'Likely cause: <svelte:options customElement={...}> tag name violates web-components rules (must be lowercase + contain at least one hyphen).';
+	}
+
+	return null;
+}
+
+function formatBytes(n) {
+	if (n < KB) return `${n} B`;
+	return `${(n / KB).toFixed(1)} KB`;
+}
+
+function printSuccess(result, durationMs, options = {}) {
+	const islands = result.bundledIslands ?? [];
+	const cssBytes = (result.css ?? '').length;
+	const htmlBytes = (result.html ?? '').length;
+	const totalIslandBytes = islands.reduce((s, i) => s + (i.size ?? i.content?.length ?? 0), 0);
+	const total = htmlBytes + cssBytes + totalIslandBytes;
+
+	console.log();
+	console.log(pc.green('✓ Build OK') + pc.dim(`  ${durationMs.toFixed(0)} ms`));
+	console.log();
+	console.log(pc.dim('  HTML    ') + formatBytes(htmlBytes));
+	console.log(pc.dim('  CSS     ') + formatBytes(cssBytes));
+	console.log(pc.dim('  Islands ') + `${islands.length}`);
+
+	if (islands.length > 0) {
+		const showAll = options.verbose || islands.length <= 6;
+		const head = showAll ? islands : islands.slice(0, 5);
+		for (const i of head) {
+			const size = i.size ?? i.content?.length ?? 0;
+			console.log(pc.dim('    ' + i.file.padEnd(38)) + formatBytes(size));
+		}
+		if (!showAll) {
+			console.log(pc.dim(`    … ${islands.length - 5} more (use --verbose for full list)`));
+		}
+	}
+	console.log();
+	console.log(pc.dim('  Total bundle: ') + pc.bold(formatBytes(total)));
+}
+
+function printFailure(err, durationMs) {
+	console.log();
+	console.log(pc.red('✖ Build failed') + pc.dim(`  ${durationMs.toFixed(0)} ms`));
+	console.log();
+	const msg = err?.message ?? String(err);
+	// The error message often includes a multi-line esbuild block — indent
+	// the whole thing two spaces so it visually nests under the heading.
+	const indented = msg.split('\n').map((l) => '  ' + l).join('\n');
+	console.log(indented);
+
+	const hint = diagnoseError(msg);
+	if (hint) {
+		console.log();
+		console.log(pc.yellow('  Hint:'));
+		console.log(pc.yellow('  ' + hint));
+	}
+	console.log();
+}
+
+/**
+ * Persist build artefacts so the developer can inspect them with their
+ * editor. Layout matches what the cloud build-service writes to R2.
+ */
+function writeArtefacts(outDir, result) {
+	rmSync(outDir, { recursive: true, force: true });
+	mkdirSync(outDir, { recursive: true });
+	if (result.html != null) {
+		writeFileSync(join(outDir, 'component.html'), result.html);
+	}
+	if (result.css != null) {
+		writeFileSync(join(outDir, 'component.css'), result.css);
+	}
+	const islands = result.bundledIslands ?? [];
+	if (islands.length > 0) {
+		const islandsDir = join(outDir, 'islands');
+		mkdirSync(islandsDir, { recursive: true });
+		for (const i of islands) {
+			const file = i.file;
+			const target = join(islandsDir, file);
+			mkdirSync(dirname(target), { recursive: true });
+			writeFileSync(target, i.content);
+		}
+	}
+}
+
+export async function buildCommand(componentArg, options = {}) {
+	const rootDir = resolveComponentDir(componentArg);
+
+	if (!existsSync(rootDir)) {
+		console.error(pc.red(`✖ Directory not found: ${rootDir}`));
+		process.exit(1);
+	}
+	const stat = statSync(rootDir);
+	if (!stat.isDirectory()) {
+		console.error(pc.red(`✖ Not a directory: ${rootDir}`));
+		process.exit(1);
+	}
+
+	const componentName = basename(rootDir);
+	console.log(pc.dim(`Building ${pc.cyan(componentName)} from ${rootDir}`));
+
+	let files;
+	try {
+		files = readComponentFiles(rootDir).files;
+	} catch (err) {
+		console.error(pc.red(`✖ Failed to read component files: ${err.message}`));
+		process.exit(1);
+	}
+
+	let payload;
+	try {
+		payload = buildPayloadFromFiles(files, componentName);
+	} catch (err) {
+		console.error(pc.red(`✖ ${err.message}`));
+		process.exit(1);
+	}
+
+	// The buildComponent function logs progress to stdout/stderr via
+	// console.log/error. That noise drowns out our clean summary on a
+	// successful build. Capture it and replay only when --verbose or on
+	// failure (so users still see what crashed).
+	const captured = [];
+	const origLog = console.log;
+	const origInfo = console.info;
+	const origErr = console.error;
+	const sink = (...args) => {
+		captured.push(args.join(' '));
+	};
+	if (!options.verbose) {
+		console.log = sink;
+		console.info = sink;
+		console.error = sink;
+	}
+
+	const t0 = performance.now();
+	let result;
+	let buildError = null;
+	try {
+		result = await buildComponent(payload);
+	} catch (err) {
+		buildError = err;
+	}
+	const duration = performance.now() - t0;
+
+	if (!options.verbose) {
+		console.log = origLog;
+		console.info = origInfo;
+		console.error = origErr;
+	}
+
+	if (buildError) {
+		// On failure, the captured internal logs are exactly the breadcrumb
+		// trail the user needs — replay them right above our pretty error.
+		if (!options.verbose && captured.length > 0) {
+			console.log(pc.dim('--- build log ---'));
+			for (const line of captured) console.log(pc.dim(line));
+			console.log(pc.dim('--- end build log ---'));
+		}
+		printFailure(buildError, duration);
+		process.exit(1);
+	}
+
+	if (!result || result.success === false) {
+		printFailure(new Error(result?.error ?? 'Unknown build failure'), duration);
+		process.exit(1);
+	}
+
+	printSuccess(result, duration, options);
+
+	if (options.out) {
+		const outDir = resolve(process.cwd(), options.out);
+		try {
+			writeArtefacts(outDir, result);
+			console.log();
+			console.log(pc.dim('  Artefacts written to ') + pc.cyan(outDir));
+		} catch (err) {
+			console.error(pc.yellow(`  ⚠ Failed to write artefacts: ${err.message}`));
+		}
+	}
+}