dekit-cli 0.1.0 → 0.2.0

package/src/cli/resolve.test.ts

@@ -0,0 +1,43 @@
+import { describe, test, expect, beforeEach, afterEach, vi } from "vitest";
+import { mkdtempSync, rmSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { runInit } from "./init.js";
+import { parseDesignConfig } from "../parser.js";
+import { runResolve } from "./resolve.js";
+
+let tempDir: string;
+
+beforeEach(async () => {
+  tempDir = mkdtempSync(join(tmpdir(), "dekit-resolve-"));
+  await runInit([tempDir, "--template", "landing"]);
+});
+
+afterEach(() => {
+  rmSync(tempDir, { recursive: true, force: true });
+});
+
+describe("runResolve", () => {
+  test("resolves page ref to file path", async () => {
+    const config = await parseDesignConfig(join(tempDir, "dekit.yaml"));
+    const spy = vi.spyOn(console, "log");
+    await runResolve(config, ["$${home}"]);
+    expect(spy.mock.calls[0][0]).toContain("pages/home/home.html");
+    spy.mockRestore();
+  });
+
+  test("resolves element ref to file path with line range", async () => {
+    const config = await parseDesignConfig(join(tempDir, "dekit.yaml"));
+    const spy = vi.spyOn(console, "log");
+    await runResolve(config, ["$${home@.hero}"]);
+    const output = spy.mock.calls[0][0] as string;
+    expect(output).toContain("pages/home/home.html");
+    expect(output).toMatch(/:\d+(-\d+)?$/);
+    spy.mockRestore();
+  });
+
+  test("rejects unknown page", async () => {
+    const config = await parseDesignConfig(join(tempDir, "dekit.yaml"));
+    await expect(runResolve(config, ["$${nonexistent}"])).rejects.toThrow(/not found/i);
+  });
+});

package/src/cli/resolve.ts

@@ -0,0 +1,92 @@
+import { readFileSync } from "node:fs";
+import { join, relative } from "node:path";
+import type { DesignConfig } from "../types.js";
+import { parseRef } from "../ref.js";
+
+export async function runResolve(config: DesignConfig, args: string[]) {
+  const refStr = args[0];
+  if (!refStr) {
+    console.error("Usage: dekit resolve <ref>");
+    process.exit(1);
+  }
+
+  const ref = parseRef(refStr);
+
+  const pageDef = config.pages[ref.pageKey];
+  if (!pageDef) {
+    throw new Error(`Page "${ref.pageKey}" not found in dekit.yaml`);
+  }
+
+  const templatePath = join(config.baseDir, pageDef.template);
+  const relPath = relative(process.cwd(), templatePath);
+
+  if (ref.type === "page") {
+    console.log(relPath);
+    return;
+  }
+
+  // Try to find the element in the source HTML by selector heuristic
+  const html = readFileSync(templatePath, "utf-8");
+  const range = findSelectorInHtml(html, ref.selector);
+
+  if (range) {
+    console.log(`${relPath}:${range.start}-${range.end}`);
+  } else {
+    console.log(relPath);
+  }
+}
+
+interface LineRange {
+  start: number;
+  end: number;
+}
+
+function findSelectorInHtml(html: string, selector: string): LineRange | null {
+  let searchPattern: RegExp | null = null;
+
+  if (selector.startsWith("#")) {
+    const id = selector.slice(1);
+    searchPattern = new RegExp(`id=["']${escapeRegex(id)}["']`);
+  } else if (selector.startsWith(".")) {
+    const cls = selector.slice(1).split(/[.\s]/)[0];
+    searchPattern = new RegExp(`class=["'][^"']*\\b${escapeRegex(cls)}\\b[^"']*["']`);
+  } else {
+    const tag = selector.split(/[:.\s>\[]/)[0];
+    if (tag) {
+      searchPattern = new RegExp(`<${escapeRegex(tag)}[\\s>]`);
+    }
+  }
+
+  if (!searchPattern) return null;
+
+  const lines = html.split("\n");
+  for (let i = 0; i < lines.length; i++) {
+    if (searchPattern.test(lines[i])) {
+      const startLine = i + 1;
+      const endLine = findClosingLine(lines, i);
+      return { start: startLine, end: endLine };
+    }
+  }
+
+  return null;
+}
+
+function findClosingLine(lines: string[], openLine: number): number {
+  const openIndent = lines[openLine].search(/\S/);
+  for (let i = openLine + 1; i < lines.length; i++) {
+    const line = lines[i];
+    if (line.trim() === "") continue;
+    const indent = line.search(/\S/);
+    if (indent <= openIndent && line.trim().startsWith("</")) {
+      return i + 1;
+    }
+    if (indent < openIndent && !line.trim().startsWith("</")) {
+      return i;
+    }
+  }
+  return lines.length;
+}
+
+function escapeRegex(s: string): string {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}

package/src/cli/screenshot.test.ts

@@ -0,0 +1,54 @@
+import { describe, test, expect, beforeEach, afterEach } from "vitest";
+import { mkdtempSync, existsSync, rmSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { runInit } from "./init.js";
+import { parseDesignConfig } from "../parser.js";
+import { runScreenshot } from "./screenshot.js";
+import { findChrome } from "../chrome.js";
+
+let tempDir: string;
+let hasChrome = false;
+
+beforeEach(async () => {
+  tempDir = mkdtempSync(join(tmpdir(), "dekit-screenshot-"));
+  await runInit([tempDir, "--template", "landing"]);
+  try {
+    await findChrome();
+    hasChrome = true;
+  } catch {
+    hasChrome = false;
+  }
+});
+
+afterEach(() => {
+  rmSync(tempDir, { recursive: true, force: true });
+});
+
+describe("runScreenshot", () => {
+  test.skipIf(!hasChrome)("takes a page screenshot", async () => {
+    const config = await parseDesignConfig(join(tempDir, "dekit.yaml"));
+    await runScreenshot(config, ["$${home}"]);
+    expect(existsSync(join(config.baseDir, "screenshots/home.png"))).toBe(true);
+  }, 30000);
+
+  test.skipIf(!hasChrome)("takes element screenshot", async () => {
+    const config = await parseDesignConfig(join(tempDir, "dekit.yaml"));
+    await runScreenshot(config, ["$${home@.hero}"]);
+    // Output filename sanitizes the selector
+    const screenshots = join(config.baseDir, "screenshots");
+    expect(existsSync(screenshots)).toBe(true);
+  }, 30000);
+
+  test.skipIf(!hasChrome)("respects -o flag", async () => {
+    const config = await parseDesignConfig(join(tempDir, "dekit.yaml"));
+    const outPath = join(tempDir, "my-shot.png");
+    await runScreenshot(config, ["$${home}", "-o", outPath]);
+    expect(existsSync(outPath)).toBe(true);
+  }, 30000);
+
+  test("rejects invalid ref format", async () => {
+    const config = await parseDesignConfig(join(tempDir, "dekit.yaml"));
+    await expect(runScreenshot(config, ["invalid"])).rejects.toThrow();
+  });
+});

package/src/cli/screenshot.ts

@@ -0,0 +1,154 @@
+import type { DesignConfig } from "../types.js";
+import { parseRef } from "../ref.js";
+import { findChrome } from "../chrome.js";
+import { dekitPlugin } from "../vite-plugin-dekit.js";
+import { DEVICE_PRESETS } from "../devices.js";
+import { mkdirSync } from "node:fs";
+import { join, dirname } from "node:path";
+import puppeteer from "puppeteer-core";
+import { createServer } from "vite";
+
+function sanitizeSelector(selector: string): string {
+  return selector.replace(/[^a-zA-Z0-9_-]/g, "_");
+}
+
+function parseArgs(args: string[]): {
+  ref: string;
+  outputPath?: string;
+  deviceName?: string;
+  width?: number;
+  height?: number;
+  fullPage: boolean;
+} {
+  let ref: string | undefined;
+  let outputPath: string | undefined;
+  let deviceName: string | undefined;
+  let width: number | undefined;
+  let height: number | undefined;
+  let fullPage = false;
+
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (arg === "-o" || arg === "--output") {
+      outputPath = args[++i];
+    } else if (arg === "--device") {
+      deviceName = args[++i];
+    } else if (arg === "--width") {
+      width = parseInt(args[++i], 10);
+    } else if (arg === "--height") {
+      height = parseInt(args[++i], 10);
+    } else if (arg === "--full-page") {
+      fullPage = true;
+    } else if (!arg.startsWith("-")) {
+      ref = arg;
+    }
+  }
+
+  if (!ref) {
+    throw new Error("Missing ref argument. Expected format: $${page} or $${page@selector}");
+  }
+
+  return { ref, outputPath, deviceName, width, height, fullPage };
+}
+
+export async function runScreenshot(config: DesignConfig, args: string[]) {
+  const { ref, outputPath, deviceName, width, height, fullPage } = parseArgs(args);
+
+  // Parse and validate the ref (throws on invalid format)
+  const parsedRef = parseRef(ref);
+
+  // Resolve viewport from --device or --width/--height flags
+  let viewportWidth = 1280;
+  let viewportHeight = 800;
+  let devicePixelRatio = 1;
+
+  if (deviceName) {
+    const normalizedInput = deviceName.toLowerCase().replace(/\s+/g, "-");
+    const preset = DEVICE_PRESETS.find(
+      (d) => d.name.toLowerCase().replace(/\s+/g, "-") === normalizedInput
+    );
+    if (!preset) {
+      throw new Error(
+        `Unknown device: "${deviceName}". Available: ${DEVICE_PRESETS.map((d) => d.name).join(", ")}`
+      );
+    }
+    viewportWidth = preset.width;
+    viewportHeight = preset.height;
+    devicePixelRatio = preset.dpr;
+  }
+
+  if (width !== undefined) viewportWidth = width;
+  if (height !== undefined) viewportHeight = height;
+
+  // Determine output path
+  const screenshotsDir = join(config.baseDir, "screenshots");
+  let resolvedOutputPath: string;
+
+  if (outputPath) {
+    resolvedOutputPath = outputPath;
+  } else if (parsedRef.type === "page") {
+    resolvedOutputPath = join(screenshotsDir, `${parsedRef.pageKey}.png`);
+  } else {
+    const safeName = `${parsedRef.pageKey}_${sanitizeSelector(parsedRef.selector)}`;
+    resolvedOutputPath = join(screenshotsDir, `${safeName}.png`);
+  }
+
+  // Ensure output directory exists
+  mkdirSync(dirname(resolvedOutputPath), { recursive: true });
+
+  // Find Chrome
+  const executablePath = await findChrome();
+
+  // Start a temporary Vite dev server
+  const configRef = { current: config };
+  const server = await createServer({
+    plugins: [dekitPlugin(configRef)],
+    server: { port: 0, strictPort: false },
+    logLevel: "silent",
+  });
+  await server.listen();
+
+  const address = server.httpServer!.address();
+  if (!address || typeof address === "string") {
+    await server.close();
+    throw new Error("Failed to determine Vite server port");
+  }
+  const port = address.port;
+
+  // Launch headless Chrome
+  const browser = await puppeteer.launch({
+    executablePath,
+    headless: true,
+    args: ["--no-sandbox", "--disable-setuid-sandbox"],
+  });
+
+  try {
+    const page = await browser.newPage();
+    await page.setViewport({
+      width: viewportWidth,
+      height: viewportHeight,
+      deviceScaleFactor: devicePixelRatio,
+    });
+
+    const pageKey = parsedRef.pageKey;
+    const url = `http://localhost:${port}/page/${pageKey}?noinspector`;
+    await page.goto(url, { waitUntil: "networkidle0" });
+
+    if (parsedRef.type === "element") {
+      const element = await page.$(parsedRef.selector);
+      if (!element) {
+        throw new Error(
+          `Element not found: "${parsedRef.selector}" on page "${pageKey}"`
+        );
+      }
+      await element.screenshot({ path: resolvedOutputPath });
+    } else {
+      await page.screenshot({ path: resolvedOutputPath, fullPage });
+    }
+
+    console.log(resolvedOutputPath);
+  } finally {
+    await browser.close();
+    await server.close();
+  }
+}

package/src/cli/usage.ts

@@ -0,0 +1,8 @@
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+
+export async function runUsage() {
+  const guidePath = join(import.meta.dirname, "../../docs/usage.md");
+  const content = readFileSync(guidePath, "utf-8");
+  console.log(content);
+}

package/src/devices.ts

@@ -0,0 +1,23 @@
+export interface DevicePreset {
+  name: string;
+  width: number;
+  height: number;
+  dpr: number;
+}
+
+export const DEVICE_PRESETS: DevicePreset[] = [
+  { name: "iPhone SE", width: 375, height: 667, dpr: 2 },
+  { name: "iPhone 14", width: 390, height: 844, dpr: 3 },
+  { name: "iPhone 14 Pro", width: 393, height: 852, dpr: 3 },
+  { name: "iPhone 14 Pro Max", width: 430, height: 932, dpr: 3 },
+  { name: "iPhone 16", width: 393, height: 852, dpr: 3 },
+  { name: "iPhone 16 Pro Max", width: 440, height: 956, dpr: 3 },
+  { name: "iPad Mini", width: 744, height: 1133, dpr: 2 },
+  { name: "iPad Air", width: 820, height: 1180, dpr: 2 },
+  { name: 'iPad Pro 12.9"', width: 1024, height: 1366, dpr: 2 },
+  { name: "Samsung Galaxy S24", width: 360, height: 780, dpr: 3 },
+  { name: "Pixel 8", width: 412, height: 915, dpr: 2.625 },
+  { name: "Desktop 1280", width: 1280, height: 800, dpr: 1 },
+  { name: "Desktop 1440", width: 1440, height: 900, dpr: 1 },
+  { name: "Desktop 1920", width: 1920, height: 1080, dpr: 1 },
+];

package/src/injected/inspector.ts

@@ -155,6 +155,36 @@ export function generateInspectorScript(): string {
     return parts.join('/');
   }
 
+  function generateCssSelector(el) {
+      if (el.id) return '#' + el.id;
+      if (el.classList && el.classList.length > 0) {
+        for (var i = 0; i < el.classList.length; i++) {
+          var cls = el.classList[i];
+          if (document.querySelectorAll('.' + cls).length === 1) {
+            return '.' + cls;
+          }
+        }
+      }
+      var parts = [];
+      var cur = el;
+      while (cur && cur !== document.body && cur !== document.documentElement) {
+        var parent = cur.parentElement;
+        if (!parent) break;
+        var tag = cur.tagName.toLowerCase();
+        var siblings = [];
+        for (var j = 0; j < parent.children.length; j++) {
+          if (parent.children[j].tagName === cur.tagName) siblings.push(parent.children[j]);
+        }
+        if (siblings.length === 1) {
+          parts.unshift(tag);
+        } else {
+          parts.unshift(tag + ':nth-of-type(' + (siblings.indexOf(cur) + 1) + ')');
+        }
+        cur = parent;
+      }
+      return parts.join(' > ');
+    }
+
   function getNodeInfo(node) {
     const computed = getComputedStyle(node);
     const rect = node.getBoundingClientRect();
@@ -177,6 +207,7 @@ export function generateInspectorScript(): string {
     return {
       tagName: node.tagName.toLowerCase(),
       path: getNodePath(node),
+      cssSelector: generateCssSelector(node),
       attributes: attrs,
       computedStyles: styles,
       boundingRect: { x: rect.x, y: rect.y, width: rect.width, height: rect.height }

package/src/parser.test.ts

@@ -5,8 +5,8 @@ import { join } from "node:path";
 const DESIGN_DIR = join(import.meta.dirname, "../example");
 
 describe("parseDesignConfig", () => {
-  test("parses valid design.yaml", async () => {
-    const config = await parseDesignConfig(join(DESIGN_DIR, "design.yaml"));
+  test("parses valid dekit.yaml", async () => {
+    const config = await parseDesignConfig(join(DESIGN_DIR, "dekit.yaml"));
     expect(config.version).toBe(1.0);
     expect(config.globalStyle).toBe("global.css");
     expect(config.components["my-banner"]).toEqual({
@@ -21,7 +21,7 @@ describe("parseDesignConfig", () => {
   });
 
   test("stores resolved base directory", async () => {
-    const config = await parseDesignConfig(join(DESIGN_DIR, "design.yaml"));
+    const config = await parseDesignConfig(join(DESIGN_DIR, "dekit.yaml"));
     expect(config.baseDir).toBe(DESIGN_DIR);
   });
 
@@ -36,7 +36,7 @@ components:
 pages: {}
 `;
     await expect(
-      parseDesignConfig("/fake/design.yaml", yaml)
+      parseDesignConfig("/fake/dekit.yaml", yaml)
     ).rejects.toThrow(/hyphen/i);
   });
 
@@ -51,7 +51,7 @@ pages:
     style: "pages/cover/cover.css"
 `;
     await expect(
-      parseDesignConfig(join(DESIGN_DIR, "design.yaml"), yaml)
+      parseDesignConfig(join(DESIGN_DIR, "dekit.yaml"), yaml)
     ).rejects.toThrow(/not found|does not exist/i);
   });
 
@@ -62,7 +62,7 @@ components: {}
 pages: {}
 `;
     await expect(
-      parseDesignConfig("/fake/design.yaml", yaml)
+      parseDesignConfig("/fake/dekit.yaml", yaml)
     ).rejects.toThrow(/version/i);
   });
 });

package/src/parser.ts

@@ -14,11 +14,11 @@ export async function parseDesignConfig(
   const doc = yaml.load(content) as Record<string, unknown>;
 
   if (!doc || typeof doc !== "object") {
-    throw new Error("Invalid design.yaml: not a valid YAML object");
+    throw new Error("Invalid config: not a valid YAML object");
   }
 
   if (doc.version == null) {
-    throw new Error("Invalid design.yaml: missing 'version' field");
+    throw new Error("Invalid config: missing 'version' field");
   }
 
   // Validate file paths if the base directory actually exists on disk

package/src/ref.test.ts

@@ -0,0 +1,68 @@
+import { describe, test, expect } from "vitest";
+import { parseRef, formatPageRef, formatElementRef } from "./ref.js";
+
+describe("parseRef", () => {
+  test("parses page ref", () => {
+    expect(parseRef("$${home}")).toEqual({ type: "page", pageKey: "home" });
+  });
+
+  test("parses element ref with class selector", () => {
+    expect(parseRef("$${home@.hero}")).toEqual({
+      type: "element",
+      pageKey: "home",
+      selector: ".hero",
+    });
+  });
+
+  test("parses element ref with id selector", () => {
+    expect(parseRef("$${about@#main-nav}")).toEqual({
+      type: "element",
+      pageKey: "about",
+      selector: "#main-nav",
+    });
+  });
+
+  test("parses element ref with compound selector", () => {
+    expect(parseRef("$${dashboard@.sidebar > .menu}")).toEqual({
+      type: "element",
+      pageKey: "dashboard",
+      selector: ".sidebar > .menu",
+    });
+  });
+
+  test("parses element ref with nth-child", () => {
+    expect(parseRef("$${about@section:nth-child(2)}")).toEqual({
+      type: "element",
+      pageKey: "about",
+      selector: "section:nth-child(2)",
+    });
+  });
+
+  test("throws on invalid format — missing $${ prefix", () => {
+    expect(() => parseRef("home")).toThrow();
+  });
+
+  test("throws on invalid format — missing } suffix", () => {
+    expect(() => parseRef("$${home")).toThrow();
+  });
+
+  test("throws on empty page key", () => {
+    expect(() => parseRef("$${}")).toThrow();
+  });
+
+  test("throws on empty selector after @", () => {
+    expect(() => parseRef("$${home@}")).toThrow();
+  });
+});
+
+describe("formatPageRef", () => {
+  test("formats page ref", () => {
+    expect(formatPageRef("home")).toBe("$${home}");
+  });
+});
+
+describe("formatElementRef", () => {
+  test("formats element ref", () => {
+    expect(formatElementRef("home", ".hero")).toBe("$${home@.hero}");
+  });
+});

package/src/ref.ts

@@ -0,0 +1,42 @@
+import type { DekitRef } from "./types.js";
+
+const REF_PATTERN = /^\$\$\{(.+)\}$/;
+
+export function parseRef(raw: string): DekitRef {
+  const match = raw.match(REF_PATTERN);
+  if (!match) {
+    throw new Error(
+      `Invalid ref format: "${raw}". Expected format: \$\${page} or \$\${page@selector}`
+    );
+  }
+
+  const inner = match[1];
+  const atIndex = inner.indexOf("@");
+
+  if (atIndex === -1) {
+    if (!inner.trim()) {
+      throw new Error("Invalid ref: empty page key");
+    }
+    return { type: "page", pageKey: inner };
+  }
+
+  const pageKey = inner.slice(0, atIndex);
+  const selector = inner.slice(atIndex + 1);
+
+  if (!pageKey.trim()) {
+    throw new Error("Invalid ref: empty page key");
+  }
+  if (!selector.trim()) {
+    throw new Error("Invalid ref: empty selector after @");
+  }
+
+  return { type: "element", pageKey, selector };
+}
+
+export function formatPageRef(pageKey: string): string {
+  return `\$\${${pageKey}}`;
+}
+
+export function formatElementRef(pageKey: string, selector: string): string {
+  return `\$\${${pageKey}@${selector}}`;
+}

package/src/server.ts

@@ -6,6 +6,7 @@ export interface ServerOptions {
   config: DesignConfig;
   port: number;
   designPort: number;
+  noOpen?: boolean;
 }
 
 export async function startServers(options: ServerOptions) {
@@ -24,11 +25,13 @@ export async function startServers(options: ServerOptions) {
   console.log(`\n  Open ${editorUrl} in your browser\n`);
 
   // Try to open browser
-  try {
-    const open = await import("open");
-    await open.default(editorUrl);
-  } catch {
-    // Silently ignore if open fails
+  if (!options.noOpen) {
+    try {
+      const open = await import("open");
+      await open.default(editorUrl);
+    } catch {
+      // Silently ignore if open fails
+    }
   }
 
   return { designServer, editorServer };

package/src/types.ts

@@ -15,3 +15,16 @@ export interface DesignConfig {
   pages: Record<string, PageDef>;
   baseDir: string; // absolute path to directory containing design.yaml
 }
+
+export interface PageRef {
+  type: "page";
+  pageKey: string;
+}
+
+export interface ElementRef {
+  type: "element";
+  pageKey: string;
+  selector: string;
+}
+
+export type DekitRef = PageRef | ElementRef;

package/src/vite-plugin-dekit.ts

@@ -7,7 +7,8 @@ import { generateInspectorScript } from "./injected/inspector.js";
 
 export async function assemblePageHtml(
   config: DesignConfig,
-  pageName: string
+  pageName: string,
+  options?: { inspector?: boolean }
 ): Promise<string> {
   const pageDef = config.pages[pageName];
   if (!pageDef) {
@@ -22,7 +23,11 @@ export async function assemblePageHtml(
     config.components,
     config.baseDir
   );
-  const inspectorScript = generateInspectorScript();
+
+  const includeInspector = options?.inspector !== false;
+  const inspectorBlock = includeInspector
+    ? `<script>\n${generateInspectorScript()}\n</script>`
+    : "";
 
   return `<!DOCTYPE html>
 <html>
@@ -37,9 +42,7 @@ ${pageTemplate}
 <script type="module">
 ${componentScript}
 </script>
-<script>
-${inspectorScript}
-</script>
+${inspectorBlock}
 </body>
 </html>`;
 }
@@ -79,8 +82,12 @@ export function dekitPlugin(configRef: { current: DesignConfig }): Plugin {
         const pageMatch = url.match(/^\/page\/([^/?#]+)/);
         if (pageMatch) {
           const pageName = pageMatch[1];
+          const urlObj = new URL(url, "http://localhost");
+          const noInspector = urlObj.searchParams.has("noinspector");
           try {
-            const html = await assemblePageHtml(configRef.current, pageName);
+            const html = await assemblePageHtml(configRef.current, pageName, {
+              inspector: !noInspector,
+            });
             res.setHeader("Content-Type", "text/html");
             res.end(html);
           } catch (err) {