design-embed 0.1.0 → 0.2.0

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,101 @@
 # 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
+```
+
+When `components` are configured with the HTML target, two additional files are generated for each view alongside the HTML:
+
+- `ViewName.ts` — a native web component scaffold (`HTMLElement` subclass with `observedAttributes`, lifecycle hooks, and a `render()` method; no React dependency)
+- `ViewName.html` — includes `<script type="module" src="./ViewName.js"></script>` at the bottom
+
+## 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: new 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,273 @@
+#!/usr/bin/env node
+import { a as formatDiagnosticText, d as loadConfig, i as checkGeneratedFiles, n as embed, o as toJsonDiagnostics } from "./core-BLV62TaX.mjs";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, 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/commands/compile.ts
+async function runCompileCommand(flags, options = {}) {
+	const cwd = resolve(process.cwd(), getStringFlag(flags, "--cwd") ?? ".");
+	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 diagnostics = [];
+	if (!configPath) {
+		diagnostics.push({
+			code: "CONFIG_REQUIRED",
+			message: "No config file found. Create design-embed.config.ts or use --config.",
+			severity: "error"
+		});
+		printDiagnostics(diagnostics, format, quiet);
+		return 2;
+	}
+	const configResult = await loadConfig(configPath, cwd);
+	diagnostics.push(...configResult.diagnostics);
+	const config = configResult.config;
+	if (hasErrors$1(diagnostics)) {
+		printDiagnostics(diagnostics, format, quiet);
+		return 2;
+	}
+	const isCheckMode = options.check && !getBooleanFlag(flags, "--write");
+	const result = await embed({
+		config,
+		cwd,
+		dryRun: isCheckMode,
+		generateTests: !getBooleanFlag(flags, "--no-test")
+	});
+	diagnostics.push(...result.diagnostics);
+	if (hasErrors$1(diagnostics)) {
+		printDiagnostics(diagnostics, format, quiet);
+		return 2;
+	}
+	if (isCheckMode) {
+		const checkResult = checkGeneratedFiles({
+			cwd,
+			files: result.files,
+			readFile(path) {
+				return existsSync(path) ? readFileSync(path, "utf-8") : void 0;
+			}
+		});
+		diagnostics.push(...checkResult.diagnostics);
+		printDiagnostics(diagnostics, format, quiet);
+		return checkResult.ok ? 0 : 3;
+	}
+	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 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;
+	}
+	if (!getTestGenerator(config)) {
+		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 = await embed({
+		config,
+		cwd,
+		generateTests: true
+	});
+	diagnostics.push(...result.diagnostics);
+	if (hasErrors(diagnostics)) {
+		printDiagnostics(diagnostics, format, quiet);
+		return 2;
+	}
+	printDiagnostics(diagnostics, format, quiet);
+	if (!quiet && format === "text") console.log(`Success. Generated ${result.files.length} test file(s).`);
+	return 0;
+}
+function getTestGenerator(config) {
+	const target = config.output?.target;
+	return !!(target && target !== "html" && "generateTests" in target);
+}
+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 SourcePlugin,
+\ttype SourcePluginInput,
+\ttype SourcePluginResult,
+} from "design-embed";
+
+class HtmlFetcherPlugin implements 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({
+\tsource: new HtmlFetcherPlugin({
+\t\turl: "https://www.scrapethissite.com/pages/",
+\t}),
+\toutput: {
+\t\tviewName: "${viewName}",
+\t\tviewsDir: "src/generated/views",
+\t},
+});
+`;
+}
+//#endregion
+//#region packages/design-embed/src/cli.ts
+async function main() {
+	const { command, flags } = parseArgs(process.argv.slice(2));
+	if (command === "check") return runCheckCommand(flags);
+	if (command === "generate-tests") return runGenerateTestsCommand(flags);
+	if (command === "init") return runInitCommand(flags);
+	return runCompileCommand(flags);
+}
+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 {};