@flow-like/widget-bundler 0.1.1

package/src/csp.ts

@@ -0,0 +1,54 @@
+import type { WidgetCapabilities } from "@flow-like/widget-sdk";
+import { escapeHtmlAttr, insertAtHeadStart } from "./html";
+
+/** Local-only schemes every widget document may fetch and play (`LOCAL_SOURCES`). */
+export const LOCAL_CSP_SOURCES = ["data:", "blob:"] as const;
+
+/**
+ * Build the pack-time widget-document CSP: `default-src 'none'` baseline,
+ * inline script/style allowed (self-contained documents), chunk loads
+ * restricted to the bundle asset origins, local `data:`/`blob:` bytes for
+ * `connect-src` and `media-src`, and browser features from the contract
+ * `capabilities`. Contract `csp` sources are never included: hosts add them
+ * to the header they serve, and only after the viewer approves.
+ */
+export function buildCsp(
+	servingPrefix: string | null,
+	capabilities: WidgetCapabilities = {},
+): string {
+	// The bundle hash is a hash of the finished archive, so pack cannot embed a
+	// hash-specific serving URL without making the archive self-referential.
+	// Allow only the origins used by the supported web and Tauri asset servers;
+	// callers may additionally narrow/extend this with a deployment prefix.
+	if (
+		servingPrefix &&
+		(/[\s;"'<>]/.test(servingPrefix) ||
+			!/^(?:https?:\/\/|flow-widget:)/.test(servingPrefix))
+	) {
+		throw new Error("Invalid widget CSP source");
+	}
+	const assetSources = [
+		"'self'",
+		"flow-widget:",
+		"http://flow-widget.localhost",
+		...(servingPrefix ? [servingPrefix] : []),
+	].join(" ");
+	const local = LOCAL_CSP_SOURCES.join(" ");
+	const localAnd = (enabled: boolean | undefined) =>
+		enabled ? `${local} ${assetSources}` : local;
+	return [
+		"default-src 'none'",
+		`script-src 'unsafe-inline' ${capabilities.wasm ? "'wasm-unsafe-eval' " : ""}${assetSources}`,
+		`style-src 'unsafe-inline' ${assetSources}`,
+		`img-src ${local} ${assetSources}`,
+		`font-src data: ${assetSources}`,
+		`connect-src ${localAnd(capabilities.workers)}`,
+		`worker-src ${capabilities.workers ? `blob: ${assetSources}` : "'none'"}`,
+		`media-src ${localAnd(capabilities.media)}`,
+	].join("; ");
+}
+
+export function injectCspMeta(html: string, csp: string): string {
+	const meta = `<meta http-equiv="Content-Security-Policy" content="${escapeHtmlAttr(csp)}" />`;
+	return insertAtHeadStart(html, meta);
+}

package/src/dev/contract-endpoint.ts

@@ -0,0 +1,103 @@
+import { existsSync, statSync } from "node:fs";
+import { join } from "node:path";
+import {
+	type JsonValue,
+	type WidgetContract,
+	canonicalizeContract,
+} from "../contract-types";
+import { type ExtractResult, extractContract } from "../extract";
+import { type PropsFormField, derivePropsFormModel } from "./form-model";
+
+export interface ContractEndpointPayload {
+	contract: WidgetContract;
+	fixtures: Record<string, JsonValue>;
+	formModel: PropsFormField[];
+	warnings: string[];
+}
+
+/** Pure part of the contract endpoint: extraction result → response body. */
+export function buildContractPayload(
+	extracted: ExtractResult,
+): ContractEndpointPayload {
+	const contract = canonicalizeContract(extracted.contract);
+	return {
+		contract,
+		fixtures: extracted.config.fixtures ?? {},
+		formModel: derivePropsFormModel(contract),
+		warnings: extracted.warnings,
+	};
+}
+
+export interface ContractGroupRef {
+	name: string;
+	dir: string;
+}
+
+const WIDGET_ID_RE = /^[a-z0-9-]+$/;
+
+/**
+ * Resolve `GET /api/contract/<group>/<id>` to the widget's config path.
+ * Returns `null` for unknown groups or ids that are not plain widget ids
+ * (which also guards the endpoint against path traversal).
+ */
+export function resolveWidgetConfigPath(
+	groups: readonly ContractGroupRef[],
+	groupName: string,
+	widgetId: string,
+): string | null {
+	if (!WIDGET_ID_RE.test(widgetId)) return null;
+	const group = groups.find((candidate) => candidate.name === groupName);
+	if (!group) return null;
+	return join(group.dir, "src", "widgets", widgetId, "widget.config.ts");
+}
+
+/**
+ * Contract extraction cached by `widget.config.ts` mtime: each request
+ * re-checks the file so config edits are picked up, without re-running the
+ * TypeScript program when nothing changed. (Edits to imported sibling type
+ * files require touching the config file — same limitation as the Vite
+ * plugin's dev cache.)
+ */
+export class ContractCache {
+	private readonly cache = new Map<
+		string,
+		{ mtimeMs: number; result: ExtractResult }
+	>();
+
+	get(configPath: string): ExtractResult {
+		const mtimeMs = statSync(configPath).mtimeMs;
+		const cached = this.cache.get(configPath);
+		if (cached && cached.mtimeMs === mtimeMs) return cached.result;
+		const result = extractContract(configPath);
+		this.cache.set(configPath, { mtimeMs, result });
+		return result;
+	}
+}
+
+export interface ContractEndpointResponse {
+	status: number;
+	body: ContractEndpointPayload | { error: string };
+}
+
+export function handleContractRequest(
+	cache: ContractCache,
+	groups: readonly ContractGroupRef[],
+	groupName: string,
+	widgetId: string,
+): ContractEndpointResponse {
+	const configPath = resolveWidgetConfigPath(groups, groupName, widgetId);
+	if (configPath === null || !existsSync(configPath)) {
+		return {
+			status: 404,
+			body: { error: `Unknown widget '${groupName}/${widgetId}'` },
+		};
+	}
+	try {
+		return { status: 200, body: buildContractPayload(cache.get(configPath)) };
+	} catch (e) {
+		return {
+			status: 500,
+			body: { error: e instanceof Error ? e.message : String(e) },
+		};
+	}
+}

package/src/dev/form-model.ts

@@ -0,0 +1,63 @@
+import type {
+	ContractInput,
+	JsonObject,
+	JsonValue,
+	WidgetContract,
+} from "../contract-types";
+
+export type PropsFormControl =
+	| { kind: "text" }
+	| { kind: "number"; integer: boolean; min?: number; max?: number }
+	| { kind: "checkbox" }
+	| { kind: "select"; choices: string[] }
+	| { kind: "json"; schema?: JsonObject };
+
+export interface PropsFormField {
+	key: string;
+	label: string;
+	description?: string;
+	optional: boolean;
+	default?: JsonValue;
+	control: PropsFormControl;
+}
+
+function controlFor(input: ContractInput): PropsFormControl {
+	switch (input.type) {
+		case "string":
+			return { kind: "text" };
+		case "number":
+		case "integer":
+			return {
+				kind: "number",
+				integer: input.type === "integer",
+				...(input.min !== undefined && { min: input.min }),
+				...(input.max !== undefined && { max: input.max }),
+			};
+		case "boolean":
+			return { kind: "checkbox" };
+		case "enum":
+			return { kind: "select", choices: input.choices ?? [] };
+		case "json":
+			return {
+				kind: "json",
+				...(input.schema !== undefined && { schema: input.schema }),
+			};
+	}
+}
+
+/**
+ * Map a widget contract to the harness props panel's form field descriptors
+ * (one control per contract input, in contract order).
+ */
+export function derivePropsFormModel(
+	contract: WidgetContract,
+): PropsFormField[] {
+	return Object.entries(contract.inputs).map(([key, input]) => ({
+		key,
+		label: key,
+		...(input.description !== undefined && { description: input.description }),
+		optional: input.optional === true,
+		...(input.default !== undefined && { default: input.default }),
+		control: controlFor(input),
+	}));
+}