design-embed 0.1.0 → 0.1.1

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2026 Jin-Woo Lee
+Copyright (c) 2026 Jin Woo Lee
 
 Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
 

package/README.md

@@ -1,5 +1,96 @@
 # design-embed
 
-The command-line interface for design-embed.
+`design-embed` is the command-line workflow for compiling exported design into files that can live inside an application repository.
 
-It runs local HTML/CSS compilation, writes generated output, checks whether generated files are current, and invokes explicit source plugins such as `figma-html`. The CLI is the user-facing workflow layer around the core compiler: it loads config, reads design input, and formats diagnostics for humans or CI.
+The package provides:
+
+- a built-in deterministic HTML output for quick inspection
+- config loading and validation
+- generated-file writing and check mode
+- explicit source-plugin orchestration
+- target-adapter orchestration for framework output such as React
+
+Without a target adapter, `design-embed` only emits HTML. Framework packages
+such as `@design-embed/target-react` are separate adapters that must be wired
+into your config.
+
+## Quick Start
+
+Create a design HTML file:
+
+```html
+<!-- target.html -->
+<section style="padding: 24px; background: #f8fafc;">
+	<h1 style="font-size: 32px;">Welcome</h1>
+	<button data-role="primary">Get started</button>
+</section>
+```
+
+Run the compiler:
+
+```bash
+npx design-embed target.html
+```
+
+By default this uses the built-in HTML target and writes:
+
+```text
+src/generated/views/debug.html
+```
+
+## React Adapter Example
+
+Install the React target adapter alongside `design-embed`:
+
+```bash
+pnpm add design-embed @design-embed/target-react
+```
+
+Create a config file:
+
+```ts
+// design-embed.config.ts
+import { defineConfig } from "design-embed";
+import { reactTarget } from "@design-embed/target-react";
+
+export default defineConfig({
+	output: {
+		target: reactTarget,
+		viewName: "WelcomeHero",
+		viewsDir: "src/components",
+		assembliesDir: "src/pages",
+		styleMode: "inline",
+	},
+	tests: {
+		outputDir: "tests",
+	},
+});
+```
+
+Run the compiler with the config:
+
+```bash
+npx design-embed target.html --config design-embed.config.ts
+```
+
+This writes React output through the adapter:
+
+```text
+src/components/WelcomeHero.view.tsx
+src/pages/WelcomeHeroPage.tsx
+tests/WelcomeHero.reference.html
+tests/WelcomeHero.visual.spec.tsx
+```
+
+Skip adapter-provided test generation with:
+
+```bash
+npx design-embed target.html --config design-embed.config.ts --no-test
+```
+
+## How It Fits Together
+
+`design-embed` owns the user-facing CLI flow: it loads config, reads input,
+selects the built-in HTML target or a configured target adapter, writes files,
+and formats diagnostics. The framework-specific behavior stays in target
+packages that implement the shared target interface.

package/dist/cli.d.mts

@@ -0,0 +1 @@
+export { };

package/dist/cli.mjs

@@ -0,0 +1,469 @@
+#!/usr/bin/env node
+import { c as checkGeneratedFiles, d as toJsonDiagnostics, l as formatDiagnosticText, n as embed, p as loadConfig } from "./src-D3fnqGCq.mjs";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, isAbsolute, resolve } from "node:path";
+//#region packages/design-embed/src/args.ts
+function parseArgs(args) {
+	const positionals = [];
+	const flags = {};
+	for (let index = 0; index < args.length; index += 1) {
+		const value = args[index];
+		if (!value?.startsWith("--")) {
+			if (value) positionals.push(value);
+			continue;
+		}
+		const next = args[index + 1];
+		if (!next || next.startsWith("--")) {
+			flags[value] = true;
+			continue;
+		}
+		flags[value] = next;
+		index += 1;
+	}
+	const [command = "compile", ...rest] = positionals;
+	return {
+		command,
+		positionals: rest,
+		flags
+	};
+}
+function getStringFlag(flags, name) {
+	const value = flags[name];
+	return typeof value === "string" ? value : void 0;
+}
+function getBooleanFlag(flags, name) {
+	return flags[name] === true;
+}
+function getFormat(flags) {
+	return flags["--format"] === "json" ? "json" : "text";
+}
+//#endregion
+//#region packages/design-embed/src/targets/html.ts
+function emitHtmlDebug(nodes, css) {
+	const body = nodes.map((node) => emitNode(node, 0)).join("");
+	if (!css?.trim()) return body;
+	return `<style>\n${css.trim()}\n</style>\n${body}\n`;
+}
+const htmlEmitter = { emit({ nodes, css, config }) {
+	return { files: [{
+		path: `${config?.output?.viewsDir ?? "src/generated/views"}/debug.html`,
+		contents: emitHtmlDebug(nodes, css)
+	}] };
+} };
+function emitNode(node, depth) {
+	const indent = "	".repeat(depth);
+	if (node.kind === "text") return `${indent}${escapeHtml(node.text ?? "")}\n`;
+	if (node.kind === "component") return `${indent}<${node.component}></${node.component}>\n`;
+	const attributes = Object.entries(node.attributes ?? {}).sort(([left], [right]) => left.localeCompare(right)).map(([name, value]) => value === "" ? name : `${name}="${escapeAttribute(value)}"`).join(" ");
+	const openTag = attributes ? `<${node.tagName} ${attributes}>` : `<${node.tagName}>`;
+	const children = node.children ?? [];
+	if (children.length === 0) return `${indent}${openTag}</${node.tagName}>\n`;
+	return `${indent}${openTag}\n${children.map((child) => emitNode(child, depth + 1)).join("")}${indent}</${node.tagName}>\n`;
+}
+function escapeHtml(value) {
+	return value.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+}
+function escapeAttribute(value) {
+	return escapeHtml(value).replace(/"/g, "&quot;");
+}
+//#endregion
+//#region packages/design-embed/src/commands/compile.ts
+async function runCompileCommand(flags, options = {}) {
+	const cwd = resolve(process.cwd(), getStringFlag(flags, "--cwd") ?? ".");
+	const inputPath = getStringFlag(flags, "--input") ?? getStringFlag(flags, "--");
+	const explicitConfigPath = getStringFlag(flags, "--config");
+	const defaultConfigPath = resolve(cwd, "design-embed.config.ts");
+	const configPath = explicitConfigPath ?? (existsSync(defaultConfigPath) ? "design-embed.config.ts" : void 0);
+	const quiet = getBooleanFlag(flags, "--quiet");
+	const format = getFormat(flags);
+	const generateTests = !getBooleanFlag(flags, "--no-test");
+	const diagnostics = [];
+	if (!inputPath) {
+		diagnostics.push({
+			code: "INPUT_REQUIRED",
+			message: "--input is required.",
+			severity: "error"
+		});
+		printDiagnostics(diagnostics, format, quiet);
+		return 2;
+	}
+	const resolvedInputPath = resolve(cwd, inputPath);
+	if (!existsSync(resolvedInputPath)) {
+		diagnostics.push({
+			code: "INPUT_NOT_FOUND",
+			message: `Input file not found: ${resolvedInputPath}`,
+			severity: "error",
+			file: inputPath
+		});
+		printDiagnostics(diagnostics, format, quiet);
+		return 2;
+	}
+	let config;
+	if (configPath) {
+		const configResult = await loadConfig(configPath, cwd);
+		diagnostics.push(...configResult.diagnostics);
+		config = configResult.config;
+		if (hasErrors$1(diagnostics)) {
+			printDiagnostics(diagnostics, format, quiet);
+			return 2;
+		}
+	}
+	const targetAdapter = getTargetAdapter(config);
+	const cssPath = getStringFlag(flags, "--css");
+	const html = readFileSync(resolvedInputPath, "utf-8");
+	const css = cssPath ? readFileSync(resolve(cwd, cssPath), "utf-8") : void 0;
+	const result = await embed({
+		html,
+		css,
+		configPath,
+		config,
+		cwd,
+		targetEmitter: targetAdapter.emitter
+	});
+	diagnostics.push(...result.diagnostics);
+	if (generateTests && targetAdapter.testGenerator) {
+		const testResult = targetAdapter.testGenerator.generateTests({
+			html,
+			css,
+			config: config ?? {},
+			diagnostics,
+			generatedFiles: result.files
+		});
+		result.files.push(...testResult.files);
+	}
+	if (hasErrors$1(diagnostics)) {
+		printDiagnostics(diagnostics, format, quiet);
+		return 2;
+	}
+	if (options.check && !getBooleanFlag(flags, "--write")) {
+		const checkResult = checkGeneratedFiles({
+			cwd,
+			files: result.files,
+			readFile(path) {
+				return existsSync(path) ? readFileSync(path, "utf-8") : void 0;
+			}
+		});
+		const checkDiagnostics = checkResult.diagnostics;
+		diagnostics.push(...checkDiagnostics);
+		printDiagnostics(diagnostics, format, quiet);
+		return checkResult.ok ? 0 : 3;
+	}
+	for (const file of result.files) {
+		const outPath = resolve(cwd, file.path);
+		mkdirSync(dirname(outPath), { recursive: true });
+		writeFileSync(outPath, file.contents, "utf-8");
+		if (!quiet && format === "text") console.log(`Wrote ${file.path}`);
+	}
+	printDiagnostics(diagnostics, format, quiet);
+	if (!quiet && format === "text") console.log(`Success. Generated ${result.files.length} file(s).`);
+	return 0;
+}
+function printDiagnostics(diagnostics, format, quiet) {
+	if (format === "json") {
+		console.log(JSON.stringify({ diagnostics: toJsonDiagnostics(diagnostics) }, null, 2));
+		return;
+	}
+	if (quiet) return;
+	for (const diagnostic of diagnostics) {
+		const output = formatDiagnosticText(diagnostic);
+		if (diagnostic.severity === "error") console.error(output);
+		else console.warn(output);
+	}
+}
+function getTargetAdapter(config) {
+	const target = config?.output?.target;
+	if (!target || target === "html") return { emitter: htmlEmitter };
+	return {
+		emitter: target,
+		testGenerator: "generateTests" in target ? target : void 0
+	};
+}
+function hasErrors$1(diagnostics) {
+	return diagnostics.some((diagnostic) => diagnostic.severity === "error");
+}
+//#endregion
+//#region packages/design-embed/src/commands/check.ts
+async function runCheckCommand(flags) {
+	return runCompileCommand(flags, { check: true });
+}
+//#endregion
+//#region packages/design-embed/src/commands/generateTests.ts
+async function runGenerateTestsCommand(flags) {
+	const cwd = resolve(process.cwd(), getStringFlag(flags, "--cwd") ?? ".");
+	const configPath = getStringFlag(flags, "--config") ?? "design-embed.config.ts";
+	const quiet = getBooleanFlag(flags, "--quiet");
+	const format = getFormat(flags);
+	const diagnostics = [];
+	const configResult = await loadConfig(configPath, cwd);
+	diagnostics.push(...configResult.diagnostics);
+	const config = configResult.config;
+	if (!config || hasErrors(diagnostics)) {
+		printDiagnostics(diagnostics, format, quiet);
+		return 2;
+	}
+	const source = readConfiguredSource(config, configPath, cwd, diagnostics);
+	if (!source || hasErrors(diagnostics)) {
+		printDiagnostics(diagnostics, format, quiet);
+		return 2;
+	}
+	const testGenerator = getTestGenerator(config);
+	if (!testGenerator) {
+		diagnostics.push({
+			code: "TEST_TARGET_UNSUPPORTED",
+			message: "generate-tests requires output.target to be a target adapter with generateTests().",
+			severity: "error"
+		});
+		printDiagnostics(diagnostics, format, quiet);
+		return 2;
+	}
+	const result = testGenerator.generateTests({
+		html: source.html,
+		css: source.css,
+		config,
+		diagnostics
+	});
+	if (hasErrors(diagnostics)) {
+		printDiagnostics(diagnostics, format, quiet);
+		return 2;
+	}
+	for (const file of result.files) {
+		const outPath = resolve(cwd, file.path);
+		mkdirSync(dirname(outPath), { recursive: true });
+		writeFileSync(outPath, file.contents, "utf-8");
+		if (!quiet && format === "text") console.log(`Wrote ${file.path}`);
+	}
+	printDiagnostics(diagnostics, format, quiet);
+	if (!quiet && format === "text") console.log(`Success. Generated ${result.files.length} test file(s).`);
+	return 0;
+}
+function readConfiguredSource(config, configPath, cwd, diagnostics) {
+	const source = config.tests?.source;
+	if (!source?.html) {
+		diagnostics.push({
+			code: "TEST_SOURCE_HTML_REQUIRED",
+			message: "tests.source.html is required for generate-tests.",
+			severity: "error"
+		});
+		return;
+	}
+	const configDir = dirname(resolve(cwd, configPath));
+	const htmlPath = resolveConfigPath(source.html, configDir);
+	if (!existsSync(htmlPath)) {
+		diagnostics.push({
+			code: "TEST_SOURCE_HTML_NOT_FOUND",
+			message: `Test source HTML not found: ${htmlPath}`,
+			severity: "error",
+			file: source.html
+		});
+		return;
+	}
+	let css;
+	if (source.css) {
+		const cssPath = resolveConfigPath(source.css, configDir);
+		if (!existsSync(cssPath)) {
+			diagnostics.push({
+				code: "TEST_SOURCE_CSS_NOT_FOUND",
+				message: `Test source CSS not found: ${cssPath}`,
+				severity: "error",
+				file: source.css
+			});
+			return;
+		}
+		css = readFileSync(cssPath, "utf-8");
+	}
+	return {
+		html: readFileSync(htmlPath, "utf-8"),
+		css
+	};
+}
+function resolveConfigPath(path, configDir) {
+	return isAbsolute(path) ? path : resolve(configDir, path);
+}
+function getTestGenerator(config) {
+	const target = config.output?.target;
+	return target && target !== "html" && "generateTests" in target ? target : void 0;
+}
+function hasErrors(diagnostics) {
+	return diagnostics.some((diagnostic) => diagnostic.severity === "error");
+}
+//#endregion
+//#region packages/design-embed/src/commands/init.ts
+async function runInitCommand(flags) {
+	const cwd = resolve(process.cwd(), getStringFlag(flags, "--cwd") ?? ".");
+	const quiet = getBooleanFlag(flags, "--quiet");
+	const force = getBooleanFlag(flags, "--force");
+	const format = getFormat(flags);
+	const viewName = getStringFlag(flags, "--view-name") ?? "WelcomeHero";
+	const diagnostics = [];
+	const files = [{
+		path: "design-embed.config.ts",
+		contents: configTemplate(viewName)
+	}];
+	let written = 0;
+	for (const file of files) {
+		const outPath = resolve(cwd, file.path);
+		if (existsSync(outPath) && !force) {
+			diagnostics.push({
+				code: "INIT_FILE_EXISTS",
+				message: `Skipped existing file: ${file.path}. Pass --force to overwrite it.`,
+				severity: "warning",
+				file: file.path
+			});
+			continue;
+		}
+		mkdirSync(dirname(outPath), { recursive: true });
+		writeFileSync(outPath, file.contents, "utf-8");
+		written += 1;
+		if (!quiet && format === "text") console.log(`Wrote ${file.path}`);
+	}
+	printDiagnostics(diagnostics, format, quiet);
+	if (!quiet && format === "text") {
+		console.log(`Success. Initialized design-embed with ${written} file(s).`);
+		console.log("Next: pnpm exec design-embed --out ./design.html");
+	}
+	return 0;
+}
+function configTemplate(viewName) {
+	return `import {
+\tdefineConfig,
+\ttype PluginDefinition,
+\ttype SourcePlugin,
+\ttype SourcePluginInput,
+\ttype SourcePluginResult,
+} from "design-embed";
+
+class HtmlFetcherPlugin implements PluginDefinition, SourcePlugin {
+\treadonly name = "html-fetcher";
+\tprivate readonly options: { url: string };
+
+\tconstructor(options: { url: string }) {
+\t\tthis.options = options;
+\t}
+
+\tasync run(_input: SourcePluginInput): Promise<SourcePluginResult> {
+\t\ttry {
+\t\t\tconst response = await fetch(this.options.url);
+\t\t\tif (!response.ok) {
+\t\t\t\treturn {
+\t\t\t\t\tdiagnostics: [
+\t\t\t\t\t\t{
+\t\t\t\t\t\t\tcode: "HTML_FETCH_FAILED",
+\t\t\t\t\t\t\tmessage: \`Failed to fetch HTML: \${response.status} \${response.statusText}\`,
+\t\t\t\t\t\t\tseverity: "error",
+\t\t\t\t\t\t},
+\t\t\t\t\t],
+\t\t\t\t};
+\t\t\t}
+
+\t\t\treturn {
+\t\t\t\thtml: await response.text(),
+\t\t\t\tdiagnostics: [],
+\t\t\t};
+\t\t} catch (error) {
+\t\t\treturn {
+\t\t\t\tdiagnostics: [
+\t\t\t\t\t{
+\t\t\t\t\t\tcode: "HTML_FETCH_FAILED",
+\t\t\t\t\t\tmessage: error instanceof Error ? error.message : String(error),
+\t\t\t\t\t\tseverity: "error",
+\t\t\t\t\t},
+\t\t\t\t],
+\t\t\t};
+\t\t}
+\t}
+}
+
+export default defineConfig({
+\tplugins: [
+\t\tnew HtmlFetcherPlugin({
+\t\t\turl: "https://www.scrapethissite.com/pages/",
+\t\t}),
+\t],
+\toutput: {
+\t\tviewName: "${viewName}",
+\t\tviewsDir: "src/generated/views",
+\t},
+});
+`;
+}
+//#endregion
+//#region packages/design-embed/src/commands/plugin.ts
+async function runPluginCommand(_name, flags) {
+	const cwd = resolve(process.cwd(), getStringFlag(flags, "--cwd") ?? ".");
+	const configResult = await loadConfig(getStringFlag(flags, "--config") ?? "design-embed.config.ts", cwd);
+	for (const diagnostic of configResult.diagnostics) if (diagnostic.severity === "error") console.error(`error: ${diagnostic.code}: ${diagnostic.message}`);
+	else console.warn(`${diagnostic.severity}: ${diagnostic.code}: ${diagnostic.message}`);
+	if (configResult.diagnostics.some((d) => d.severity === "error")) return 2;
+	const outPath = getStringFlag(flags, "--out");
+	if (!outPath) {
+		console.error("Error: --out is required.");
+		return 2;
+	}
+	const plugin = findSourcePlugin(configResult.config?.plugins);
+	if (!plugin) {
+		console.error("Error: config must include a source plugin instance in the plugins array (e.g. new FigmaHtmlPlugin({ ... })).");
+		return 2;
+	}
+	const result = await plugin.run({
+		cwd,
+		args: {}
+	});
+	for (const diagnostic of result.diagnostics) {
+		const output = `${diagnostic.severity}: ${diagnostic.code}: ${diagnostic.message}`;
+		if (diagnostic.severity === "error") console.error(output);
+		else console.warn(output);
+	}
+	if (result.diagnostics.some((d) => d.severity === "error")) return 2;
+	if (!result.html) {
+		console.error("Error: source plugin produced no HTML.");
+		return 2;
+	}
+	const resolvedOutPath = resolve(cwd, outPath);
+	mkdirSync(dirname(resolvedOutPath), { recursive: true });
+	writeFileSync(resolvedOutPath, result.html, "utf-8");
+	console.log(`Wrote ${outPath}`);
+	for (const file of result.files ?? []) {
+		const resolvedPath = resolve(cwd, file.path);
+		mkdirSync(dirname(resolvedPath), { recursive: true });
+		writeFileSync(resolvedPath, file.contents, "utf-8");
+		console.log(`Wrote ${file.path}`);
+	}
+	return 0;
+}
+function isSourcePlugin(plugin) {
+	return typeof plugin.run === "function";
+}
+function findSourcePlugin(plugins) {
+	return plugins?.find(isSourcePlugin);
+}
+//#endregion
+//#region packages/design-embed/src/cli.ts
+async function main() {
+	const args = process.argv.slice(2);
+	const parsed = parseArgs(args);
+	if (args[0] === "check") return runCheckCommand(parsed.flags);
+	if (args[0] === "plugin") return runPluginCommand(parsed.positionals[0], parsed.flags);
+	if (args[0] === "generate-tests") return runGenerateTestsCommand(parsed.flags);
+	if (args[0] === "init") return runInitCommand(parsed.flags);
+	const flags = args[0] && !args[0].startsWith("--") ? {
+		...parsed.flags,
+		"--": args[0]
+	} : parsed.flags;
+	if (getOutPath(flags) && !hasInput(flags)) return runPluginCommand(void 0, flags);
+	return runCompileCommand(flags);
+}
+function getOutPath(flags) {
+	return typeof flags["--out"] === "string";
+}
+function hasInput(flags) {
+	return typeof flags["--input"] === "string" || typeof flags["--"] === "string";
+}
+main().then((code) => {
+	if (code !== 0) process.exit(code);
+}).catch((error) => {
+	const message = error instanceof Error ? error.message : String(error);
+	console.error(`Pipeline failed: ${message}`);
+	process.exit(1);
+});
+//#endregion
+export {};