design-embed 0.1.0

package/LICENSE

@@ -0,0 +1,9 @@
+MIT License
+
+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:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -0,0 +1,5 @@
+# design-embed
+
+The command-line interface for design-embed.
+
+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.

package/dist/args.js

@@ -0,0 +1,36 @@
+export 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,
+    };
+}
+export function getStringFlag(flags, name) {
+    const value = flags[name];
+    return typeof value === "string" ? value : undefined;
+}
+export function getBooleanFlag(flags, name) {
+    return flags[name] === true;
+}
+export function getFormat(flags) {
+    return flags["--format"] === "json" ? "json" : "text";
+}

package/dist/cli.js

@@ -0,0 +1,35 @@
+#!/usr/bin/env node
+import { parseArgs } from "./args.js";
+import { runCheckCommand } from "./commands/check.js";
+import { runCompileCommand } from "./commands/compile.js";
+import { runGenerateTestsCommand } from "./commands/generateTests.js";
+import { runInitCommand } from "./commands/init.js";
+import { runPluginCommand } from "./commands/plugin.js";
+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);
+    }
+    return runCompileCommand(parsed.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);
+});

package/dist/commands/check.js

@@ -0,0 +1,4 @@
+import { runCompileCommand } from "./compile.js";
+export async function runCheckCommand(flags) {
+    return runCompileCommand(flags, { check: true });
+}

package/dist/commands/compile.js

@@ -0,0 +1,157 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, isAbsolute, resolve } from "node:path";
+import { loadConfig } from "@design-embed/config";
+import { checkGeneratedFiles, embed, formatDiagnosticText, toJsonDiagnostics, } from "@design-embed/core";
+import { htmlEmitter } from "@design-embed/target-html";
+import { reactEmitter } from "@design-embed/target-react";
+import { getBooleanFlag, getFormat, getStringFlag } from "../args.js";
+export async function runCompileCommand(flags, options = {}) {
+    const cwd = resolve(process.cwd(), getStringFlag(flags, "--cwd") ?? ".");
+    const inputPath = getStringFlag(flags, "--input");
+    const configPath = getStringFlag(flags, "--config");
+    const quiet = getBooleanFlag(flags, "--quiet");
+    const format = getFormat(flags);
+    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;
+    let transformers = [];
+    if (configPath) {
+        const configResult = await loadConfig(configPath, cwd);
+        diagnostics.push(...configResult.diagnostics);
+        config = configResult.config;
+        if (hasErrors(diagnostics)) {
+            printDiagnostics(diagnostics, format, quiet);
+            return 2;
+        }
+        transformers = await loadTransformers(config, configPath, cwd, diagnostics);
+        if (hasErrors(diagnostics)) {
+            printDiagnostics(diagnostics, format, quiet);
+            return 2;
+        }
+    }
+    const target = config?.output?.target ?? "html";
+    const targetEmitter = target === "react" ? reactEmitter : htmlEmitter;
+    const cssPath = getStringFlag(flags, "--css");
+    const result = await embed({
+        html: readFileSync(resolvedInputPath, "utf-8"),
+        css: cssPath ? readFileSync(resolve(cwd, cssPath), "utf-8") : undefined,
+        configPath,
+        config,
+        cwd,
+        transformers,
+        targetEmitter,
+    });
+    diagnostics.push(...result.diagnostics);
+    if (hasErrors(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") : undefined;
+            },
+        });
+        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;
+}
+export 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 isPackageName(path) {
+    return !path.startsWith(".") && !isAbsolute(path);
+}
+async function loadTransformers(config, configPath, cwd, diagnostics) {
+    const configDir = dirname(resolve(cwd, configPath));
+    const loaded = [];
+    for (const transformer of config?.transformers ?? []) {
+        const specifier = isPackageName(transformer.path)
+            ? transformer.path
+            : isAbsolute(transformer.path)
+                ? transformer.path
+                : resolve(configDir, transformer.path);
+        try {
+            const module = await import(specifier);
+            const plugin = module.default ?? module.transformer;
+            if (!plugin?.transform) {
+                diagnostics.push({
+                    code: "TRANSFORMER_INVALID",
+                    message: `Transformer ${transformer.path} must export a plugin object with transform().`,
+                    severity: "error",
+                    file: transformer.path,
+                });
+                continue;
+            }
+            loaded.push({
+                name: plugin.name ?? transformer.path,
+                order: transformer.order ?? plugin.order,
+                transform: plugin.transform,
+            });
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            diagnostics.push({
+                code: "TRANSFORMER_LOAD_FAILED",
+                message: `Failed to load transformer ${transformer.path}: ${message}`,
+                severity: "error",
+                file: transformer.path,
+            });
+        }
+    }
+    return loaded;
+}
+function hasErrors(diagnostics) {
+    return diagnostics.some((diagnostic) => diagnostic.severity === "error");
+}

package/dist/commands/generateTests.js

@@ -0,0 +1,113 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, isAbsolute, resolve } from "node:path";
+import { loadConfig } from "@design-embed/config";
+import { reactTestGenerator } from "@design-embed/target-react";
+import { getBooleanFlag, getFormat, getStringFlag } from "../args.js";
+import { printDiagnostics } from "./compile.js";
+export async function runGenerateTestsCommand(flags) {
+    const cwd = resolve(process.cwd(), getStringFlag(flags, "--cwd") ?? ".");
+    const configPath = getStringFlag(flags, "--config");
+    const quiet = getBooleanFlag(flags, "--quiet");
+    const format = getFormat(flags);
+    const diagnostics = [];
+    if (!configPath) {
+        diagnostics.push({
+            code: "CONFIG_REQUIRED",
+            message: "--config is required for generate-tests.",
+            severity: "error",
+        });
+        printDiagnostics(diagnostics, format, quiet);
+        return 2;
+    }
+    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 target = config.output?.target ?? "html";
+    if (target !== "react") {
+        diagnostics.push({
+            code: "TEST_TARGET_UNSUPPORTED",
+            message: `generate-tests currently supports target "react"; received "${target}".`,
+            severity: "error",
+        });
+        printDiagnostics(diagnostics, format, quiet);
+        return 2;
+    }
+    const result = reactTestGenerator.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 undefined;
+    }
+    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 undefined;
+    }
+    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 undefined;
+        }
+        css = readFileSync(cssPath, "utf-8");
+    }
+    return {
+        html: readFileSync(htmlPath, "utf-8"),
+        css,
+    };
+}
+function resolveConfigPath(path, configDir) {
+    return isAbsolute(path) ? path : resolve(configDir, path);
+}
+function hasErrors(diagnostics) {
+    return diagnostics.some((diagnostic) => diagnostic.severity === "error");
+}

package/dist/commands/init.js

@@ -0,0 +1,102 @@
+import { existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { getBooleanFlag, getFormat, getStringFlag } from "../args.js";
+import { printDiagnostics } from "./compile.js";
+export 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),
+        },
+        {
+            path: "design.html",
+            contents: designHtmlTemplate(),
+        },
+        {
+            path: "playwright-ct.config.ts",
+            contents: playwrightConfigTemplate(),
+        },
+    ];
+    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 --input ./design.html --config ./design-embed.config.ts");
+    }
+    return 0;
+}
+function configTemplate(viewName) {
+    return `import { defineConfig } from "design-embed";
+
+export default defineConfig({
+\toutput: {
+\t\ttarget: "react",
+\t\tviewName: "${viewName}",
+\t\tviewsDir: "src/generated/views",
+\t\tstyleMode: "inline",
+\t},
+\ttests: {
+\t\toutputDir: "tests/generated/design-embed",
+\t\trunner: "playwright",
+\t\tsource: {
+\t\t\thtml: "./design.html",
+\t\t},
+\t\tviewports: [
+\t\t\t{ name: "mobile", width: 390, height: 844 },
+\t\t\t{ name: "desktop", width: 1440, height: 900 },
+\t\t],
+\t\tstates: [{ name: "default" }],
+\t\tassertions: {
+\t\t\tscreenshot: true,
+\t\t\tlayout: true,
+\t\t\tlayoutTolerance: 1,
+\t\t\tselectors: [":scope", ":scope *"],
+\t\t},
+\t},
+});
+`;
+}
+function designHtmlTemplate() {
+    return `<section style="box-sizing: border-box; width: 320px; padding: 24px; border-radius: 16px; background: #f8fafc; color: #0f172a; font-family: Arial, sans-serif;">
+\t<p style="margin: 0 0 8px; color: #2563eb; font-size: 14px; font-weight: 700;">Design Embed</p>
+\t<h1 style="margin: 0 0 12px; font-size: 32px; line-height: 1.1;">Welcome hero</h1>
+\t<p style="margin: 0 0 20px; font-size: 16px; line-height: 1.5;">Replace this file with HTML exported from your design source.</p>
+\t<button data-role="primary" style="border: 0; border-radius: 999px; padding: 12px 18px; background: #2563eb; color: white; font-size: 14px; font-weight: 700;">Get started</button>
+</section>
+`;
+}
+function playwrightConfigTemplate() {
+    return `import { defineConfig } from "@playwright/experimental-ct-react";
+
+export default defineConfig({
+\ttestDir: ".",
+\tuse: {
+\t\tctPort: 3100,
+\t},
+});
+`;
+}

package/dist/commands/plugin.js

@@ -0,0 +1,68 @@
+import { mkdirSync, writeFileSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { loadConfig } from "@design-embed/config";
+import { getStringFlag } from "../args.js";
+export async function runPluginCommand(_name, flags) {
+    const configPath = getStringFlag(flags, "--config");
+    if (!configPath) {
+        console.error("Error: --config is required.");
+        return 2;
+    }
+    const cwd = process.cwd();
+    const configResult = await loadConfig(configPath, 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);
+}

package/dist/index.js

@@ -0,0 +1,2 @@
+export * from "@design-embed/config";
+export * from "@design-embed/core";

package/node_modules/@design-embed/config/README.md

@@ -0,0 +1,5 @@
+# @design-embed/config
+
+Internal configuration loading and validation for design-embed.
+
+It parses the project config format used by the compiler, validates supported output targets, style modes, component mappings, token settings, plugin settings, and local transformer declarations. It also reports config diagnostics in a stable shape so callers can fail early before compilation begins.