@flow-like/widget-bundler 0.1.1

package/src/validate-cmd.ts

@@ -0,0 +1,268 @@
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { unzipSync } from "fflate";
+import {
+	BUNDLE_FORMAT_VERSION,
+	BUNDLE_MANIFEST_PATH,
+	type WidgetBundleManifest,
+	isSafeEntryPath,
+	unsafeArchiveEntryPaths,
+} from "./bundle-format";
+import {
+	WIDGET_PROTOCOL,
+	type WidgetContract,
+	isValidPackageId,
+	validateContract,
+	validatePublishedCsp,
+} from "./contract-types";
+import { extractContract, networkInputSchemaErrors } from "./extract";
+import {
+	archiveNameCollisions,
+	discoverGroupWidgets,
+	discoverGroups,
+	entryHash,
+	readPackageInfo,
+} from "./pack";
+
+export interface ProjectValidation {
+	ok: boolean;
+	errors: string[];
+	warnings: string[];
+	widgets: { id: string; group: string }[];
+}
+
+/** Validate contract extraction for every widget in a project (no build required). */
+export function validateProject(projectDir: string): ProjectValidation {
+	const errors: string[] = [];
+	const warnings: string[] = [];
+	const widgets: { id: string; group: string }[] = [];
+
+	try {
+		readPackageInfo(projectDir);
+	} catch (e) {
+		errors.push(e instanceof Error ? e.message : String(e));
+	}
+
+	const groups = discoverGroups(projectDir);
+	if (groups.length === 0) {
+		errors.push(
+			`No framework groups found under ${join(projectDir, "widgets")} (expected widgets/<group>/package.json)`,
+		);
+	}
+
+	const seenIds = new Set<string>();
+	for (const group of groups) {
+		for (const widgetId of discoverGroupWidgets(group.dir)) {
+			const configPath = join(
+				group.dir,
+				"src",
+				"widgets",
+				widgetId,
+				"widget.config.ts",
+			);
+			try {
+				const extracted = extractContract(configPath);
+				warnings.push(...extracted.warnings);
+				if (extracted.config.id !== widgetId) {
+					errors.push(
+						`Widget id '${extracted.config.id}' in ${configPath} does not match its directory name '${widgetId}'`,
+					);
+				}
+				if (seenIds.has(widgetId)) {
+					errors.push(
+						`Duplicate widget id across framework groups: ${widgetId}`,
+					);
+				}
+				seenIds.add(widgetId);
+				widgets.push({ id: widgetId, group: group.name });
+			} catch (e) {
+				errors.push(e instanceof Error ? e.message : String(e));
+			}
+		}
+	}
+
+	if (groups.length > 0 && widgets.length === 0 && errors.length === 0) {
+		errors.push(
+			"No widgets found (expected widgets/<group>/src/widgets/<id>/widget.config.ts)",
+		);
+	}
+
+	return { ok: errors.length === 0, errors, warnings, widgets };
+}
+
+export interface BundleValidation {
+	ok: boolean;
+	errors: string[];
+	manifest: WidgetBundleManifest | null;
+}
+
+/**
+ * Validate a built `.flwb`: manifest shape, unsafe and colliding archive
+ * names, per-entry hashes, contract validity (including the `csp` purpose
+ * rules and the v1/v2 rule), exact entry paths. Mirrors
+ * `WidgetBundleReader::validate` in packages/wasm/schema/src/widget_bundle.rs,
+ * plus the checks only the hub publish and the bundler run: wildcard bases,
+ * address-like reasons and network input schema reachability.
+ */
+export function validateBundle(flwbPath: string): BundleValidation {
+	const errors: string[] = [];
+	if (!existsSync(flwbPath)) {
+		return {
+			ok: false,
+			errors: [`Bundle not found: ${flwbPath}`],
+			manifest: null,
+		};
+	}
+
+	let entries: Record<string, Uint8Array>;
+	try {
+		entries = unzipSync(new Uint8Array(readFileSync(flwbPath)));
+	} catch (e) {
+		return {
+			ok: false,
+			errors: [
+				`Failed to read widget bundle ZIP: ${e instanceof Error ? e.message : e}`,
+			],
+			manifest: null,
+		};
+	}
+
+	const manifestBytes = entries[BUNDLE_MANIFEST_PATH];
+	if (!manifestBytes) {
+		return {
+			ok: false,
+			errors: [`Widget bundle is missing ${BUNDLE_MANIFEST_PATH}`],
+			manifest: null,
+		};
+	}
+	let manifest: WidgetBundleManifest;
+	try {
+		manifest = JSON.parse(new TextDecoder().decode(manifestBytes));
+	} catch (e) {
+		return {
+			ok: false,
+			errors: [
+				`Failed to parse bundle.json: ${e instanceof Error ? e.message : e}`,
+			],
+			manifest: null,
+		};
+	}
+
+	if (
+		manifest.formatVersion === 0 ||
+		manifest.formatVersion > BUNDLE_FORMAT_VERSION
+	) {
+		errors.push(
+			`Unsupported bundle format version ${manifest.formatVersion} (supported: 1..=${BUNDLE_FORMAT_VERSION})`,
+		);
+	}
+	if (manifest.protocol !== WIDGET_PROTOCOL) {
+		errors.push(
+			`Unsupported widget protocol '${manifest.protocol}' (expected '${WIDGET_PROTOCOL}')`,
+		);
+	}
+	if (!manifest.packageId) {
+		errors.push("Bundle manifest is missing packageId");
+	} else if (!isValidPackageId(manifest.packageId)) {
+		errors.push(
+			`Invalid bundle packageId ${JSON.stringify(manifest.packageId)}: use only letters, digits, '.', '_' and '-'`,
+		);
+	}
+	if (!manifest.widgets || manifest.widgets.length === 0) {
+		errors.push("Bundle contains no widgets");
+	}
+	const names = Object.keys(entries);
+	errors.push(...unsafeArchiveEntryPaths(names));
+	errors.push(...archiveNameCollisions(names));
+
+	const sharedPaths = new Set<string>();
+	for (const shared of manifest.shared ?? []) {
+		sharedPaths.add(shared.path);
+		if (!isSafeEntryPath(shared.path) || !shared.path.startsWith("shared/")) {
+			errors.push(`Invalid shared chunk path: ${shared.path}`);
+			continue;
+		}
+		const data = entries[shared.path];
+		if (!data) {
+			errors.push(`Widget bundle entry not found: ${shared.path}`);
+			continue;
+		}
+		const actual = entryHash(data);
+		if (actual !== shared.hash) {
+			errors.push(
+				`Hash mismatch for shared chunk ${shared.path}: expected ${shared.hash}, got ${actual}`,
+			);
+		}
+	}
+
+	const seenIds = new Set<string>();
+	for (const widget of manifest.widgets ?? []) {
+		if (seenIds.has(widget.id)) {
+			errors.push(`Duplicate widget id in bundle: ${widget.id}`);
+		}
+		seenIds.add(widget.id);
+		const expectedEntry = `widgets/${widget.id}/index.html`;
+		if (widget.entry !== expectedEntry) {
+			errors.push(
+				`Widget '${widget.id}' entry path '${widget.entry}' must be '${expectedEntry}'`,
+			);
+		}
+		const expectedContract = `widgets/${widget.id}/contract.json`;
+		if (widget.contract !== expectedContract) {
+			errors.push(
+				`Widget '${widget.id}' contract path '${widget.contract}' must be '${expectedContract}'`,
+			);
+		}
+
+		const entryData = entries[widget.entry];
+		if (!entryData) {
+			errors.push(`Widget bundle entry not found: ${widget.entry}`);
+		} else {
+			const actual = entryHash(entryData);
+			if (actual !== widget.entryHash) {
+				errors.push(
+					`Hash mismatch for widget entry ${widget.entry}: expected ${widget.entryHash}, got ${actual}`,
+				);
+			}
+		}
+
+		const contractData = entries[widget.contract];
+		if (!contractData) {
+			errors.push(`Widget bundle entry not found: ${widget.contract}`);
+		} else {
+			try {
+				const contract: WidgetContract = JSON.parse(
+					new TextDecoder().decode(contractData),
+				);
+				if (contract.id !== widget.id) {
+					errors.push(
+						`Contract id '${contract.id}' does not match widget id '${widget.id}'`,
+					);
+				}
+				const contractErrors = validateContract(contract);
+				errors.push(
+					...(contractErrors.length > 0
+						? contractErrors
+						: [
+								...validatePublishedCsp(contract),
+								...networkInputSchemaErrors(contract),
+							]),
+				);
+			} catch (e) {
+				errors.push(
+					`Failed to parse contract for widget '${widget.id}': ${e instanceof Error ? e.message : e}`,
+				);
+			}
+		}
+
+		for (const asset of widget.assets ?? []) {
+			if (!sharedPaths.has(asset)) {
+				errors.push(
+					`Widget '${widget.id}' references undeclared asset: ${asset}`,
+				);
+			}
+		}
+	}
+
+	return { ok: errors.length === 0, errors, manifest };
+}

package/src/vite.ts

@@ -0,0 +1,109 @@
+import { existsSync, readdirSync, statSync } from "node:fs";
+import { dirname, join, relative, resolve, sep } from "node:path";
+import type { HtmlTagDescriptor, Plugin } from "vite";
+import { type ExtractResult, extractContract } from "./extract";
+import { contractScriptContent } from "./inline";
+
+export interface WidgetEntry {
+	id: string;
+	htmlPath: string;
+}
+
+/** Find `src/widgets/{id}/index.html` entrypoints of a framework group. */
+export function discoverWidgetEntries(rootDir: string): WidgetEntry[] {
+	const widgetsDir = join(rootDir, "src", "widgets");
+	if (!existsSync(widgetsDir)) return [];
+	const entries: WidgetEntry[] = [];
+	for (const name of readdirSync(widgetsDir).sort()) {
+		const dir = join(widgetsDir, name);
+		if (!statSync(dir).isDirectory()) continue;
+		const htmlPath = join(dir, "index.html");
+		if (existsSync(htmlPath)) entries.push({ id: name, htmlPath });
+	}
+	return entries;
+}
+
+export function widgetIdFromHtmlPath(
+	rootDir: string,
+	filePath: string,
+): string | null {
+	const rel = relative(resolve(rootDir), resolve(filePath))
+		.split(sep)
+		.join("/");
+	const match = /^src\/widgets\/([^/]+)\/index\.html$/.exec(rel);
+	return match?.[1] ?? null;
+}
+
+const extractCache = new Map<
+	string,
+	{ mtimeMs: number; result: ExtractResult }
+>();
+
+function cachedExtract(configPath: string): ExtractResult {
+	const mtimeMs = statSync(configPath).mtimeMs;
+	const cached = extractCache.get(configPath);
+	if (cached && cached.mtimeMs === mtimeMs) return cached.result;
+	const result = extractContract(configPath);
+	extractCache.set(configPath, { mtimeMs, result });
+	return result;
+}
+
+/**
+ * Contract script tag for a widget `index.html`, or `null` when the page is
+ * not a widget entry (dev parity with `pack`, which re-injects the contract).
+ */
+export function contractTagForHtml(
+	rootDir: string,
+	htmlFilePath: string,
+): HtmlTagDescriptor | null {
+	const id = widgetIdFromHtmlPath(rootDir, htmlFilePath);
+	if (!id) return null;
+	const configPath = join(dirname(resolve(htmlFilePath)), "widget.config.ts");
+	if (!existsSync(configPath)) return null;
+	const { contract } = cachedExtract(configPath);
+	return {
+		tag: "script",
+		children: contractScriptContent(contract),
+		injectTo: "head-prepend",
+	};
+}
+
+/**
+ * Vite plugin for widget framework groups: discovers `src/widgets/{id}/index.html`
+ * as build inputs (one entry per widget id), routes entry/chunk/asset output
+ * into `shared/` so `pack` can collect deduplicated chunks, and injects the
+ * extracted `__FLW_CONTRACT__` script during dev/build.
+ */
+export function flowLikeWidgets(): Plugin {
+	let root = process.cwd();
+	return {
+		name: "flow-like-widgets",
+		config(userConfig) {
+			root = resolve(userConfig.root ?? process.cwd());
+			const entries = discoverWidgetEntries(root);
+			if (entries.length === 0) return {};
+			return {
+				build: {
+					rollupOptions: {
+						input: Object.fromEntries(
+							entries.map((entry) => [entry.id, entry.htmlPath]),
+						),
+						output: {
+							entryFileNames: "shared/[name]-[hash].js",
+							chunkFileNames: "shared/[name]-[hash].js",
+							assetFileNames: "shared/[name]-[hash][extname]",
+						},
+					},
+				},
+			};
+		},
+		transformIndexHtml: {
+			order: "pre",
+			handler(html, ctx) {
+				const tag = contractTagForHtml(root, ctx.filename);
+				if (!tag) return;
+				return { html, tags: [tag] };
+			},
+		},
+	};
+}