dekit-cli 0.1.0 → 0.2.0

package/dist/editor/index.html

@@ -4,7 +4,7 @@
   <meta charset="UTF-8">
   <meta name="viewport" content="width=device-width, initial-scale=1.0">
   <title>Dekit Editor</title>
-  <script type="module" crossorigin src="/assets/index-DK9iczjI.js"></script>
+  <script type="module" crossorigin src="/assets/index-yt1AtkL3.js"></script>
   <link rel="stylesheet" crossorigin href="/assets/index-Bx5YsS46.css">
 </head>
 <body>

package/docs/usage.md

@@ -0,0 +1,127 @@
+# Dekit — Agent Usage Guide
+
+Dekit is a design canvas for code agents. You write HTML/CSS, dekit renders and screenshots it.
+
+## Core Concepts
+
+- **Page**: An HTML file + CSS file registered in `dekit.yaml`
+- **Component**: A reusable Web Component (custom element with shadow DOM)
+- **Ref**: A reference to a page or element: `$${page}` or `$${page@selector}`
+
+## Quick Start
+
+```bash
+# Initialize a new design project
+dekit init my-design --template landing
+
+# Preview in browser
+cd my-design
+dekit serve
+
+# Take a screenshot
+dekit screenshot '$${home}'
+```
+
+## CLI Reference
+
+### dekit init [path] [--template name]
+
+Initialize a design project. Templates: `blank`, `landing`, `dashboard`, `mobile`.
+
+```bash
+dekit init                           # In current directory, blank template
+dekit init design/                   # In subdirectory
+dekit init --template landing        # With template
+dekit init --template                # List available templates
+```
+
+### dekit add page <name> [--template name]
+
+Add a page. Templates: `blank`, `hero`, `form`, `grid`.
+
+```bash
+dekit add page about
+dekit add page pricing --template grid
+```
+
+### dekit add component <name>
+
+Add a Web Component (name must contain a hyphen).
+
+```bash
+dekit add component my-card
+```
+
+### dekit ls
+
+List all pages and components.
+
+### dekit serve [-p port] [--no-open]
+
+Start the interactive preview server.
+
+### dekit screenshot <ref> [options]
+
+Take a screenshot. Output path is printed to stdout.
+
+```bash
+dekit screenshot '$${home}'                    # Full page
+dekit screenshot '$${home@.hero}'              # Element only
+dekit screenshot '$${home}' --device iphone-14 # Device size
+dekit screenshot '$${home}' --full-page        # Include scroll
+dekit screenshot '$${home}' -o my-shot.png     # Custom output
+dekit screenshot --all                         # All pages
+```
+
+### dekit resolve <ref>
+
+Resolve a ref to source file path and line range.
+
+```bash
+dekit resolve '$${home}'
+# → pages/home/home.html
+
+dekit resolve '$${home@.hero}'
+# → pages/home/home.html:1-10
+```
+
+### dekit usage
+
+Print this guide.
+
+## Ref Protocol
+
+Format: `$${page-key}` or `$${page-key@css-selector}`
+
+When you see a `$${...}` pattern, pass it to `dekit resolve` or `dekit screenshot`.
+
+- `dekit resolve <ref>` → file path + line range
+- `dekit screenshot <ref>` → screenshot file path
+
+## Design Loop
+
+```
+1. dekit init --template landing     # Start project
+2. Edit HTML/CSS files               # Make changes
+3. dekit screenshot '$${home}'       # See result
+4. Analyze the screenshot            # Check quality
+5. Edit again                        # Fix issues
+6. Repeat 3-5                        # Until satisfied
+```
+
+## dekit.yaml Format
+
+```yaml
+version: 1.0
+global-style: "global.css"
+
+components:
+  my-card:
+    template: "components/my-card/my-card.html"
+    style: "components/my-card/my-card.css"
+
+pages:
+  home:
+    template: "pages/home/home.html"
+    style: "pages/home/home.css"
+```

package/editor/src/App.tsx

@@ -33,20 +33,18 @@ export function App() {
   const currentPageRef = useRef("");
   const canvasAreaRef = useRef<HTMLDivElement>(null);
   const [canvasSize, setCanvasSize] = useState({ width: 0, height: 0 });
-  const [contextMenu, setContextMenu] = useState<{ x: number; y: number; domPath?: string; page: string } | null>(null);
+  const [contextMenu, setContextMenu] = useState<{ x: number; y: number; cssSelector?: string; page: string } | null>(null);
   const [focusedPanel, setFocusedPanel] = useState<"pages" | "layers" | null>(null);
 
   const configRef = useRef<EditorConfig | null>(null);
   configRef.current = config;
 
   const getPageRef = useCallback((page: string) => {
-    const filePath = configRef.current?.pagePaths?.[page] ?? page;
-    return "$$" + "{" + filePath + "}";
+    return "$$" + "{" + page + "}";
   }, []);
 
-  const getNodeRef = useCallback((page: string, domPath: string) => {
-    const filePath = configRef.current?.pagePaths?.[page] ?? page;
-    return "$$" + "{" + filePath + "#" + domPath + "}";
+  const getNodeRef = useCallback((page: string, cssSelector: string) => {
+    return "$$" + "{" + page + "@" + cssSelector + "}";
   }, []);
 
   // Fetch config
@@ -70,7 +68,7 @@ export function App() {
         setSelectedNode(msg.node);
         setSelectedPath(msg.node.path);
         if (inspectModeRef.current && currentPageRef.current) {
-          navigator.clipboard.writeText(getNodeRef(currentPageRef.current, msg.node.path));
+          navigator.clipboard.writeText(getNodeRef(currentPageRef.current, msg.node.cssSelector));
           iframeRef.current?.contentWindow?.postMessage({ type: "COPY_FEEDBACK" }, "*");
         }
       } else if (msg.type === "DOM_TREE") {
@@ -372,7 +370,7 @@ export function App() {
                     setFocusedPanel("layers");
                   }}
                   onHover={handleLayerHover}
-                  onContextMenu={(domPath, x, y) => setContextMenu({ x, y, domPath, page: currentPage })}
+                  onContextMenu={(cssSelector, x, y) => setContextMenu({ x, y, cssSelector, page: currentPage })}
                 />
               ))}
             </div>
@@ -382,7 +380,7 @@ export function App() {
           <div className="panel-header">Properties</div>
           <OverlayScrollbarsComponent className="properties-scroll" defer>
             {selectedNode ? (
-              <PropertyPanel node={selectedNode} nodeRef={getNodeRef(currentPage, selectedNode.path)} />
+              <PropertyPanel node={selectedNode} nodeRef={getNodeRef(currentPage, selectedNode.cssSelector)} />
             ) : (
               <div className="empty-state">Select an element to inspect</div>
             )}
@@ -396,11 +394,11 @@ export function App() {
           style={{ left: contextMenu.x, top: contextMenu.y }}
           onClick={(e) => e.stopPropagation()}
         >
-          {contextMenu.domPath && (
+          {contextMenu.cssSelector && (
             <div
               className="context-menu-item"
               onClick={() => {
-                navigator.clipboard.writeText(getNodeRef(contextMenu.page, contextMenu.domPath!));
+                navigator.clipboard.writeText(getNodeRef(contextMenu.page, contextMenu.cssSelector!));
                 setContextMenu(null);
               }}
             >

package/editor/src/types.ts

@@ -1,6 +1,7 @@
 export interface NodeInfo {
   tagName: string;
   path: string;
+  cssSelector: string;
   attributes: Record<string, string>;
   computedStyles: Record<string, string>;
   boundingRect: { x: number; y: number; width: number; height: number };

package/package.json

@@ -1,15 +1,39 @@
 {
   "name": "dekit-cli",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "type": "module",
-  "description": "A code-first design toolkit — preview, inspect, and debug your HTML/CSS designs in the browser",
-  "keywords": ["design", "devtools", "inspector", "preview", "css", "html", "cli"],
+  "description": "A code-first design toolkit for agents and humans — create, preview, and screenshot HTML/CSS designs",
+  "keywords": [
+    "design",
+    "devtools",
+    "inspector",
+    "preview",
+    "css",
+    "html",
+    "cli",
+    "agent",
+    "ai"
+  ],
   "license": "Apache-2.0",
-  "repository": { "type": "git", "url": "https://github.com/myWsq/dekit" },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/myWsq/dekit"
+  },
   "homepage": "https://github.com/myWsq/dekit",
-  "bugs": { "url": "https://github.com/myWsq/dekit/issues" },
-  "files": ["bin/", "src/", "editor/", "dist/"],
-  "engines": { "node": ">=18" },
+  "bugs": {
+    "url": "https://github.com/myWsq/dekit/issues"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "editor/",
+    "dist/",
+    "templates/",
+    "docs/usage.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
   "bin": {
     "dekit": "./bin/dekit.ts"
   },
@@ -24,6 +48,7 @@
     "open": "^10.1.0",
     "overlayscrollbars": "^2.14.0",
     "overlayscrollbars-react": "^0.5.6",
+    "puppeteer-core": "^24.40.0",
     "react-icons": "^5.6.0",
     "sirv": "^3.0.0",
     "vite": "^6.2.0"
@@ -32,11 +57,11 @@
     "@types/js-yaml": "^4.0.9",
     "@types/react": "^19.0.0",
     "@types/react-dom": "^19.0.0",
+    "@vitejs/plugin-react": "^4.3.0",
     "react": "^19.0.0",
     "react-dom": "^19.0.0",
     "tsx": "^4.19.0",
     "typescript": "^5.7.0",
-    "vitest": "^3.0.0",
-    "@vitejs/plugin-react": "^4.3.0"
+    "vitest": "^3.0.0"
   }
 }

package/src/chrome.test.ts

@@ -0,0 +1,24 @@
+import { describe, test, expect, vi, afterEach } from "vitest";
+import { findChrome } from "./chrome.js";
+
+afterEach(() => {
+  vi.unstubAllEnvs();
+});
+
+describe("findChrome", () => {
+  test("returns CHROME_PATH if set and exists", async () => {
+    vi.stubEnv("CHROME_PATH", process.execPath);
+    const result = await findChrome();
+    expect(result).toBe(process.execPath);
+  });
+
+  test("returns a string on systems with Chrome installed", async () => {
+    vi.stubEnv("CHROME_PATH", "");
+    try {
+      const result = await findChrome();
+      expect(typeof result).toBe("string");
+    } catch (err) {
+      expect((err as Error).message).toContain("Chrome not found");
+    }
+  });
+});

package/src/chrome.ts

@@ -0,0 +1,37 @@
+import { existsSync } from "node:fs";
+import { platform } from "node:os";
+
+const CHROME_PATHS: Record<string, string[]> = {
+  darwin: [
+    "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome",
+    "/Applications/Chromium.app/Contents/MacOS/Chromium",
+  ],
+  linux: [
+    "/usr/bin/google-chrome",
+    "/usr/bin/google-chrome-stable",
+    "/usr/bin/chromium-browser",
+    "/usr/bin/chromium",
+  ],
+  win32: [
+    "C:\\Program Files\\Google\\Chrome\\Application\\chrome.exe",
+    "C:\\Program Files (x86)\\Google\\Chrome\\Application\\chrome.exe",
+  ],
+};
+
+export async function findChrome(): Promise<string> {
+  const envPath = process.env.CHROME_PATH;
+  if (envPath && existsSync(envPath)) {
+    return envPath;
+  }
+
+  const candidates = CHROME_PATHS[platform()] ?? [];
+  for (const candidate of candidates) {
+    if (existsSync(candidate)) {
+      return candidate;
+    }
+  }
+
+  throw new Error(
+    "Chrome not found. Install Chrome or set CHROME_PATH environment variable."
+  );
+}

package/src/cli/add.test.ts

@@ -0,0 +1,62 @@
+import { describe, test, expect, beforeEach, afterEach } from "vitest";
+import { mkdtempSync, readFileSync, rmSync, existsSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { runInit } from "./init.js";
+import { runAdd } from "./add.js";
+import { parseDesignConfig } from "../parser.js";
+
+let tempDir: string;
+
+beforeEach(async () => {
+  tempDir = mkdtempSync(join(tmpdir(), "dekit-add-"));
+  await runInit([tempDir]);
+});
+
+afterEach(() => {
+  rmSync(tempDir, { recursive: true, force: true });
+});
+
+describe("runAdd page", () => {
+  test("adds a new page with blank template", async () => {
+    const config = await parseDesignConfig(join(tempDir, "dekit.yaml"));
+    await runAdd(config, ["page", "about"]);
+
+    expect(existsSync(join(tempDir, "pages/about/about.html"))).toBe(true);
+    expect(existsSync(join(tempDir, "pages/about/about.css"))).toBe(true);
+
+    const updatedYaml = readFileSync(join(tempDir, "dekit.yaml"), "utf-8");
+    expect(updatedYaml).toContain("about");
+  });
+
+  test("adds a page with hero template", async () => {
+    const config = await parseDesignConfig(join(tempDir, "dekit.yaml"));
+    await runAdd(config, ["page", "landing", "--template", "hero"]);
+
+    const html = readFileSync(join(tempDir, "pages/landing/landing.html"), "utf-8");
+    expect(html).toContain("hero");
+  });
+
+  test("rejects duplicate page name", async () => {
+    const config = await parseDesignConfig(join(tempDir, "dekit.yaml"));
+    await expect(runAdd(config, ["page", "home"])).rejects.toThrow(/already exists/i);
+  });
+});
+
+describe("runAdd component", () => {
+  test("adds a new component", async () => {
+    const config = await parseDesignConfig(join(tempDir, "dekit.yaml"));
+    await runAdd(config, ["component", "my-card"]);
+
+    expect(existsSync(join(tempDir, "components/my-card/my-card.html"))).toBe(true);
+    expect(existsSync(join(tempDir, "components/my-card/my-card.css"))).toBe(true);
+
+    const updatedYaml = readFileSync(join(tempDir, "dekit.yaml"), "utf-8");
+    expect(updatedYaml).toContain("my-card");
+  });
+
+  test("rejects component name without hyphen", async () => {
+    const config = await parseDesignConfig(join(tempDir, "dekit.yaml"));
+    await expect(runAdd(config, ["component", "card"])).rejects.toThrow(/hyphen/i);
+  });
+});

package/src/cli/add.ts

@@ -0,0 +1,104 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import yaml from "js-yaml";
+import type { DesignConfig } from "../types.js";
+
+const PAGE_TEMPLATES_DIR = join(import.meta.dirname, "../../templates/pages");
+const COMPONENT_TEMPLATES_DIR = join(import.meta.dirname, "../../templates/components");
+
+const AVAILABLE_PAGE_TEMPLATES = ["blank", "hero", "form", "grid"];
+
+export async function runAdd(config: DesignConfig, args: string[]) {
+  const type = args[0];
+  const name = args[1];
+
+  if (!type || !name) {
+    console.error("Usage: dekit add <page|component> <name> [--template <template>]");
+    process.exit(1);
+  }
+
+  let template = "blank";
+  const templateIdx = args.indexOf("--template");
+  if (templateIdx !== -1 && args[templateIdx + 1]) {
+    template = args[templateIdx + 1];
+  }
+
+  if (type === "page") {
+    await addPage(config, name, template);
+  } else if (type === "component") {
+    await addComponent(config, name);
+  } else {
+    console.error(`Unknown type: "${type}". Use "page" or "component".`);
+    process.exit(1);
+  }
+}
+
+async function addPage(config: DesignConfig, name: string, template: string) {
+  if (config.pages[name]) {
+    throw new Error(`Page "${name}" already exists`);
+  }
+
+  if (!AVAILABLE_PAGE_TEMPLATES.includes(template)) {
+    throw new Error(
+      `Unknown page template: "${template}". Available: ${AVAILABLE_PAGE_TEMPLATES.join(", ")}`
+    );
+  }
+
+  const pageDir = join(config.baseDir, "pages", name);
+  mkdirSync(pageDir, { recursive: true });
+
+  const templateDir = join(PAGE_TEMPLATES_DIR, template);
+  const htmlSrc = readFileSync(join(templateDir, "page.html"), "utf-8");
+  const cssSrc = readFileSync(join(templateDir, "page.css"), "utf-8");
+
+  writeFileSync(join(pageDir, `${name}.html`), htmlSrc.replace(/__PAGE_NAME__/g, name));
+  writeFileSync(join(pageDir, `${name}.css`), cssSrc);
+
+  // Update dekit.yaml
+  const configPath = join(config.baseDir, "dekit.yaml");
+  const raw = yaml.load(readFileSync(configPath, "utf-8")) as Record<string, unknown>;
+  const pages = (raw.pages ?? {}) as Record<string, unknown>;
+  pages[name] = {
+    template: `pages/${name}/${name}.html`,
+    style: `pages/${name}/${name}.css`,
+  };
+  raw.pages = pages;
+  writeFileSync(configPath, yaml.dump(raw, { lineWidth: -1 }));
+
+  console.log(`Added page "${name}" (template: ${template})`);
+}
+
+async function addComponent(config: DesignConfig, name: string) {
+  if (!name.includes("-")) {
+    throw new Error(
+      `Component name "${name}" must contain a hyphen (Web Components spec)`
+    );
+  }
+
+  if (config.components[name]) {
+    throw new Error(`Component "${name}" already exists`);
+  }
+
+  const compDir = join(config.baseDir, "components", name);
+  mkdirSync(compDir, { recursive: true });
+
+  const templateDir = join(COMPONENT_TEMPLATES_DIR, "blank");
+  const htmlSrc = readFileSync(join(templateDir, "component.html"), "utf-8");
+  const cssSrc = readFileSync(join(templateDir, "component.css"), "utf-8");
+
+  writeFileSync(join(compDir, `${name}.html`), htmlSrc);
+  writeFileSync(join(compDir, `${name}.css`), cssSrc);
+
+  // Update dekit.yaml
+  const configPath = join(config.baseDir, "dekit.yaml");
+  const raw = yaml.load(readFileSync(configPath, "utf-8")) as Record<string, unknown>;
+  const components = (raw.components ?? {}) as Record<string, unknown>;
+  components[name] = {
+    template: `components/${name}/${name}.html`,
+    style: `components/${name}/${name}.css`,
+  };
+  raw.components = components;
+  writeFileSync(configPath, yaml.dump(raw, { lineWidth: -1 }));
+
+  console.log(`Added component "${name}"`);
+}

package/src/cli/init.test.ts

@@ -0,0 +1,61 @@
+import { describe, test, expect, beforeEach, afterEach, vi } from "vitest";
+import { mkdtempSync, existsSync, readFileSync, rmSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { runInit } from "./init.js";
+
+let tempDir: string;
+
+beforeEach(() => {
+  tempDir = mkdtempSync(join(tmpdir(), "dekit-init-"));
+});
+
+afterEach(() => {
+  rmSync(tempDir, { recursive: true, force: true });
+});
+
+describe("runInit", () => {
+  test("creates blank project in target directory", async () => {
+    const target = join(tempDir, "my-design");
+    await runInit([target]);
+
+    expect(existsSync(join(target, "dekit.yaml"))).toBe(true);
+    expect(existsSync(join(target, "global.css"))).toBe(true);
+    expect(existsSync(join(target, "pages/home/home.html"))).toBe(true);
+    expect(existsSync(join(target, "pages/home/home.css"))).toBe(true);
+  });
+
+  test("creates blank project in current directory when no path given", async () => {
+    const origCwd = process.cwd();
+    process.chdir(tempDir);
+    try {
+      await runInit([]);
+      expect(existsSync(join(tempDir, "dekit.yaml"))).toBe(true);
+    } finally {
+      process.chdir(origCwd);
+    }
+  });
+
+  test("creates landing template when specified", async () => {
+    const target = join(tempDir, "landing");
+    await runInit([target, "--template", "landing"]);
+
+    const html = readFileSync(join(target, "pages/home/home.html"), "utf-8");
+    expect(html).toContain("hero");
+  });
+
+  test("refuses to init in directory with existing dekit.yaml", async () => {
+    const target = join(tempDir, "existing");
+    await runInit([target]);
+    await expect(runInit([target])).rejects.toThrow(/already exists/i);
+  });
+
+  test("lists templates when --template given without value", async () => {
+    const consoleSpy = vi.spyOn(console, "log");
+    await runInit(["--template"]);
+    expect(consoleSpy).toHaveBeenCalledWith(
+      expect.stringContaining("blank")
+    );
+    consoleSpy.mockRestore();
+  });
+});

package/src/cli/init.ts

@@ -0,0 +1,46 @@
+import { existsSync, mkdirSync, cpSync } from "node:fs";
+import { resolve, join } from "node:path";
+
+const TEMPLATES_DIR = join(import.meta.dirname, "../../templates/projects");
+
+const AVAILABLE_TEMPLATES = ["blank", "landing", "dashboard", "mobile"];
+
+export async function runInit(args: string[]) {
+  let targetDir = process.cwd();
+  let template = "blank";
+
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (arg === "--template") {
+      const next = args[i + 1];
+      if (!next || next.startsWith("-")) {
+        console.log("Available templates: " + AVAILABLE_TEMPLATES.join(", "));
+        return;
+      }
+      template = next;
+      i++;
+    } else if (!arg.startsWith("-")) {
+      targetDir = resolve(arg);
+    }
+  }
+
+  if (!AVAILABLE_TEMPLATES.includes(template)) {
+    throw new Error(
+      `Unknown template: "${template}". Available: ${AVAILABLE_TEMPLATES.join(", ")}`
+    );
+  }
+
+  if (existsSync(join(targetDir, "dekit.yaml"))) {
+    throw new Error(`dekit.yaml already exists in ${targetDir}`);
+  }
+
+  const templateDir = join(TEMPLATES_DIR, template);
+  if (!existsSync(templateDir)) {
+    throw new Error(`Template directory not found: ${templateDir}`);
+  }
+
+  mkdirSync(targetDir, { recursive: true });
+  cpSync(templateDir, targetDir, { recursive: true });
+
+  console.log(`Created dekit project in ${targetDir} (template: ${template})`);
+}

package/src/cli/ls.test.ts

@@ -0,0 +1,29 @@
+import { describe, test, expect, vi, beforeEach, afterEach } from "vitest";
+import { mkdtempSync, rmSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { runInit } from "./init.js";
+import { runLs } from "./ls.js";
+import { parseDesignConfig } from "../parser.js";
+
+let tempDir: string;
+
+beforeEach(async () => {
+  tempDir = mkdtempSync(join(tmpdir(), "dekit-ls-"));
+  await runInit([tempDir, "--template", "landing"]);
+});
+
+afterEach(() => {
+  rmSync(tempDir, { recursive: true, force: true });
+});
+
+describe("runLs", () => {
+  test("lists pages", async () => {
+    const config = await parseDesignConfig(join(tempDir, "dekit.yaml"));
+    const spy = vi.spyOn(console, "log");
+    await runLs(config);
+    const output = spy.mock.calls.map((c) => c[0]).join("\n");
+    expect(output).toContain("home");
+    spy.mockRestore();
+  });
+});

package/src/cli/ls.ts

@@ -0,0 +1,24 @@
+import type { DesignConfig } from "../types.js";
+
+export async function runLs(config: DesignConfig) {
+  const pages = Object.keys(config.pages);
+  const components = Object.keys(config.components);
+
+  console.log("Pages:");
+  if (pages.length === 0) {
+    console.log("  (none)");
+  } else {
+    for (const name of pages) {
+      console.log(`  ${name}`);
+    }
+  }
+
+  console.log("\nComponents:");
+  if (components.length === 0) {
+    console.log("  (none)");
+  } else {
+    for (const name of components) {
+      console.log(`  ${name}`);
+    }
+  }
+}