design-clone 1.0.0

package/bin/commands/verify.js

@@ -0,0 +1,99 @@
+/**
+ * Verify command - check installation status
+ */
+
+import fs from 'fs/promises';
+import path from 'path';
+import { exists } from '../utils/copy.js';
+import { runAllChecks } from '../utils/validate.js';
+
+const getSkillDir = () => path.join(process.env.HOME || process.env.USERPROFILE || '', '.claude/skills/design-clone');
+
+/**
+ * Verify skill installation
+ */
+export async function verify() {
+  const SKILL_DIR = getSkillDir();
+  let allOk = true;
+
+  console.log('design-clone skill verification\n');
+
+  // Check skill directory
+  console.log('Installation:');
+  const skillExists = await exists(SKILL_DIR);
+  console.log(`  Skill directory: ${skillExists ? '✓' : '✗'} ${SKILL_DIR}`);
+  if (!skillExists) {
+    console.log('\n  Skill not installed. Run: design-clone init');
+    return;
+  }
+
+  // Check required files
+  const requiredFiles = [
+    'SKILL.md',
+    'multi-screenshot.js',
+    'filter-css.js',
+    'analyze-structure.py',
+    'lib/browser.js',
+    'lib/env.js',
+    'lib/env.py',
+    'requirements.txt'
+  ];
+
+  let filesOk = true;
+  for (const file of requiredFiles) {
+    const filePath = path.join(SKILL_DIR, file);
+    const fileExists = await exists(filePath);
+    if (!fileExists) {
+      console.log(`  ${file}: ✗ missing`);
+      filesOk = false;
+    }
+  }
+  if (filesOk) {
+    console.log(`  Required files: ✓ all present`);
+  } else {
+    allOk = false;
+  }
+
+  // Check node_modules
+  const nodeModulesExists = await exists(path.join(SKILL_DIR, 'node_modules'));
+  console.log(`  Node modules: ${nodeModulesExists ? '✓' : '✗'} ${nodeModulesExists ? 'installed' : 'not installed'}`);
+  if (!nodeModulesExists) allOk = false;
+
+  // Check environment
+  console.log('\nEnvironment:');
+  const checks = await runAllChecks();
+
+  console.log(`  Node.js: ${checks.node.ok ? '✓' : '✗'} ${checks.node.message}`);
+  console.log(`  Python:  ${checks.python.ok ? '✓' : '✗'} ${checks.python.message}`);
+  console.log(`  Chrome:  ${checks.chrome.ok ? '✓' : '✗'} ${checks.chrome.message}`);
+
+  if (!checks.node.ok) allOk = false;
+
+  // Check Gemini API key
+  console.log('\nOptional:');
+  const geminiKey = process.env.GEMINI_API_KEY || process.env.GOOGLE_API_KEY;
+  console.log(`  GEMINI_API_KEY: ${geminiKey ? '✓ set' : '○ not set (AI analysis disabled)'}`);
+
+  // Check .env files
+  const envLocations = [
+    path.join(SKILL_DIR, '.env'),
+    path.join(process.env.HOME || '', '.claude/skills/.env'),
+    path.join(process.env.HOME || '', '.claude/.env')
+  ];
+
+  for (const envPath of envLocations) {
+    const envExists = await exists(envPath);
+    if (envExists) {
+      console.log(`  .env found: ${envPath}`);
+      break;
+    }
+  }
+
+  // Summary
+  console.log('\nStatus:');
+  if (allOk) {
+    console.log('  ✓ Ready to use! Try /design:clone in Claude Code');
+  } else {
+    console.log('  ✗ Some issues found. Run: design-clone init --force');
+  }
+}

package/bin/utils/copy.js

@@ -0,0 +1,65 @@
+/**
+ * File copy utilities
+ */
+
+import fs from 'fs/promises';
+import path from 'path';
+
+/**
+ * Copy directory recursively
+ * @param {string} src - Source directory
+ * @param {string} dest - Destination directory
+ * @param {Object} options - Options
+ * @param {string[]} options.exclude - Patterns to exclude
+ */
+export async function copyRecursive(src, dest, options = {}) {
+  const exclude = options.exclude || [
+    'node_modules',
+    '.git',
+    '__pycache__',
+    'test-*.js',
+    'run-all-tests.js',
+    '.DS_Store',
+    '*.log'
+  ];
+
+  await fs.mkdir(dest, { recursive: true });
+
+  const entries = await fs.readdir(src, { withFileTypes: true });
+
+  for (const entry of entries) {
+    const srcPath = path.join(src, entry.name);
+    const destPath = path.join(dest, entry.name);
+
+    // Check exclusions
+    const shouldExclude = exclude.some(pattern => {
+      if (pattern.includes('*')) {
+        const regex = new RegExp('^' + pattern.replace('*', '.*') + '$');
+        return regex.test(entry.name);
+      }
+      return entry.name === pattern;
+    });
+
+    if (shouldExclude) continue;
+
+    if (entry.isDirectory()) {
+      await copyRecursive(srcPath, destPath, options);
+    } else {
+      await fs.copyFile(srcPath, destPath);
+    }
+  }
+}
+
+/**
+ * Check if path exists
+ * @param {string} filePath - Path to check
+ * @returns {Promise<boolean>}
+ */
+export async function exists(filePath) {
+  try {
+    await fs.access(filePath);
+    return true;
+  } catch {
+    return false;
+  }
+}

package/bin/utils/validate.js

@@ -0,0 +1,122 @@
+/**
+ * Environment validation utilities
+ */
+
+import { exec as execCallback } from 'child_process';
+import { promisify } from 'util';
+
+const exec = promisify(execCallback);
+
+/**
+ * Check Node.js version
+ * @returns {Promise<{ok: boolean, version: string, message: string}>}
+ */
+export async function checkNode() {
+  try {
+    const { stdout } = await exec('node --version');
+    const version = stdout.trim();
+    const major = parseInt(version.slice(1).split('.')[0], 10);
+
+    if (major >= 18) {
+      return { ok: true, version, message: `Node.js ${version}` };
+    }
+    return { ok: false, version, message: `Node.js ${version} (requires >=18)` };
+  } catch {
+    return { ok: false, version: 'unknown', message: 'Node.js not found' };
+  }
+}
+
+/**
+ * Check Python version
+ * @returns {Promise<{ok: boolean, version: string, message: string}>}
+ */
+export async function checkPython() {
+  try {
+    const { stdout } = await exec('python3 --version');
+    const version = stdout.trim().replace('Python ', '');
+    const [major, minor] = version.split('.').map(Number);
+
+    if (major >= 3 && minor >= 9) {
+      return { ok: true, version, message: `Python ${version}` };
+    }
+    return { ok: false, version, message: `Python ${version} (requires >=3.9)` };
+  } catch {
+    return { ok: false, version: 'unknown', message: 'Python 3 not found' };
+  }
+}
+
+/**
+ * Check Chrome/Chromium
+ * @returns {Promise<{ok: boolean, path: string, message: string}>}
+ */
+export async function checkChrome() {
+  const paths = {
+    darwin: [
+      '/Applications/Google Chrome.app/Contents/MacOS/Google Chrome',
+      '/Applications/Chromium.app/Contents/MacOS/Chromium'
+    ],
+    linux: [
+      '/usr/bin/google-chrome',
+      '/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'
+    ]
+  };
+
+  const platformPaths = paths[process.platform] || [];
+
+  for (const chromePath of platformPaths) {
+    try {
+      const fs = await import('fs/promises');
+      await fs.access(chromePath);
+      return { ok: true, path: chromePath, message: 'Chrome found' };
+    } catch {
+      // Continue to next path
+    }
+  }
+
+  // Try which/where command
+  try {
+    const cmd = process.platform === 'win32' ? 'where chrome' : 'which google-chrome || which chromium';
+    const { stdout } = await exec(cmd);
+    const found = stdout.trim().split('\n')[0];
+    if (found) {
+      return { ok: true, path: found, message: 'Chrome found' };
+    }
+  } catch {
+    // Not found
+  }
+
+  return { ok: false, path: '', message: 'Chrome/Chromium not found' };
+}
+
+/**
+ * Check Puppeteer
+ * @returns {Promise<{ok: boolean, message: string}>}
+ */
+export async function checkPuppeteer() {
+  try {
+    await import('puppeteer');
+    return { ok: true, message: 'Puppeteer installed' };
+  } catch {
+    return { ok: false, message: 'Puppeteer not installed (optional)' };
+  }
+}
+
+/**
+ * Run all checks
+ * @returns {Promise<Object>}
+ */
+export async function runAllChecks() {
+  const [node, python, chrome, puppeteer] = await Promise.all([
+    checkNode(),
+    checkPython(),
+    checkChrome(),
+    checkPuppeteer()
+  ]);
+
+  return { node, python, chrome, puppeteer };
+}

package/docs/basic-clone.md

@@ -0,0 +1,63 @@
+# Basic Clone Workflow
+
+Quick website design capture with screenshots and source extraction.
+
+## When to Use
+
+- Quick design reference/inspiration
+- Simple single-page sites
+- Initial exploration before pixel-perfect clone
+
+## Steps
+
+### 1. Capture Screenshots + Extract Source
+
+```bash
+node src/core/screenshot.js \
+  --url "https://example.com" \
+  --output ./cloned-design \
+  --extract-html \
+  --extract-css
+```
+
+### 2. Filter Unused CSS (Optional)
+
+```bash
+node src/core/filter-css.js \
+  --html ./cloned-design/source.html \
+  --css ./cloned-design/source-raw.css \
+  --output ./cloned-design/source.css
+```
+
+## Output Files
+
+| File | Description |
+|------|-------------|
+| desktop.png | 1920x1080 viewport screenshot |
+| tablet.png | 768x1024 viewport screenshot |
+| mobile.png | 375x812 viewport screenshot |
+| source.html | Cleaned HTML (inline styles removed) |
+| source-raw.css | All extracted CSS (unfiltered) |
+| source.css | Filtered CSS (after filter-css.js) |
+
+## Common Options
+
+```bash
+# Custom viewports
+--viewports '[{"width":1440,"height":900,"name":"laptop"}]'
+
+# Full page capture
+--full-page
+
+# Wait for animations
+--wait 3000
+
+# Skip HTML extraction
+--extract-html false
+```
+
+## Tips
+
+- Add `--wait 2000` for sites with loading animations
+- Use `--full-page` for long scrolling pages
+- Check `source.html` for missing sections before pixel-perfect

package/docs/cli-reference.md

@@ -0,0 +1,94 @@
+# CLI Reference
+
+All script options and parameters.
+
+## screenshot.js
+
+Core screenshot and extraction tool.
+
+```bash
+node src/core/screenshot.js [options]
+```
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| --url | string | required | Target URL |
+| --output | string | required | Output directory |
+| --viewports | string | all | Comma-separated: desktop,tablet,mobile |
+| --full-page | bool | true | Capture full page height |
+| --max-size | number | 5 | Max file size in MB before compression |
+| --headless | bool | false | Run in headless mode (desktop always uses headless) |
+| --scroll-delay | number | 1500 | Pause time in ms between scroll steps for lazy content |
+| --close | bool | false | Close browser after capture (false keeps session) |
+| --extract-html | bool | false | Extract cleaned HTML |
+| --extract-css | bool | false | Extract all CSS from page |
+| --filter-unused | bool | true | Filter CSS to remove unused selectors |
+| --verbose | bool | false | Verbose logging |
+
+**Output**: JSON with screenshot paths and metadata. Includes `browserRestarts` count tracking for stability monitoring.
+
+## filter-css.js
+
+Remove unused CSS selectors.
+
+```bash
+node src/core/filter-css.js --html FILE --css FILE --output FILE [--verbose]
+```
+
+| Option | Required | Description |
+|--------|----------|-------------|
+| --html | yes | Source HTML file |
+| --css | yes | Raw CSS file |
+| --output | yes | Filtered CSS output |
+| --verbose | no | Show stats |
+
+## analyze-structure.py
+
+AI structure analysis with Gemini.
+
+```bash
+python src/ai/analyze-structure.py -s SCREENSHOT -o OUTPUT [options]
+```
+
+| Option | Required | Description |
+|--------|----------|-------------|
+| -s, --screenshot | yes | Desktop screenshot |
+| -o, --output | yes | Output directory |
+| --html | no | Source HTML (improves accuracy) |
+| --css | no | Source CSS (improves accuracy) |
+| --model | no | Gemini model (default: gemini-2.5-flash) |
+| -v, --verbose | no | Verbose output |
+
+## extract-design-tokens.py
+
+Extract colors, typography, spacing.
+
+```bash
+python src/ai/extract-design-tokens.py -s SCREENSHOT -o OUTPUT [options]
+```
+
+Same options as analyze-structure.py.
+
+## extract-assets.js
+
+Download images, fonts, icons.
+
+```bash
+node src/core/extract-assets.js --url URL --output DIR
+```
+
+## verify-menu.js
+
+Validate navigation structure.
+
+```bash
+node src/verification/verify-menu.js --html FILE
+```
+
+## verify-layout.js
+
+Verify layout consistency.
+
+```bash
+node src/verification/verify-layout.js --html FILE
+```

package/docs/design-clone-architecture.md

@@ -0,0 +1,247 @@
+# Design Clone Skill Architecture
+
+Technical architecture of the design-clone skill for Claude Code.
+
+## Overview
+
+```
+design-clone/
+├── SKILL.md                 # Entry point
+├── bin/                     # npm CLI tool
+│   ├── cli.js
+│   ├── commands/
+│   └── utils/
+├── src/
+│   ├── core/                # Core scripts
+│   ├── ai/                  # AI analysis
+│   ├── verification/        # Verification scripts
+│   ├── post-process/        # Post-processing
+│   └── utils/               # Shared utilities
+├── docs/                    # Documentation
+├── templates/               # Output templates
+└── tests/                   # Test files
+```
+
+## Architecture Diagram
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                        Claude Code                               │
+│  ┌──────────────────┐  ┌──────────────────┐                     │
+│  │  /design:clone   │  │  /design:clone-px │                    │
+│  └────────┬─────────┘  └────────┬─────────┘                     │
+└───────────┼─────────────────────┼───────────────────────────────┘
+            │                     │
+            ▼                     ▼
+┌─────────────────────────────────────────────────────────────────┐
+│                        SKILL.md                                  │
+│  - Activation triggers: clone, copy, replicate website          │
+│  - Commands: design:clone, design:clone-px                      │
+│  - References: progressive disclosure                            │
+└─────────────────────────────────────────────────────────────────┘
+            │
+            ▼
+┌─────────────────────────────────────────────────────────────────┐
+│                     Core Scripts (src/)                          │
+│  ┌─────────────────┐  ┌─────────────────┐  ┌─────────────────┐ │
+│  │ core/           │  │ core/           │  │ ai/             │ │
+│  │ screenshot.js   │  │ filter-css.js   │  │ analyze-struct  │ │
+│  └────────┬────────┘  └────────┬────────┘  │     .py         │ │
+│           │                    │           └────────┬────────┘ │
+└───────────┼────────────────────┼───────────────────┼───────────┘
+            │                    │                   │
+            ▼                    ▼                   ▼
+┌─────────────────────────────────────────────────────────────────┐
+│                   src/utils/ (Shared)                            │
+│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐             │
+│  │ browser.js  │  │   env.js    │  │   env.py    │             │
+│  │  (facade)   │  │  (Node.js)  │  │  (Python)   │             │
+│  └──────┬──────┘  └─────────────┘  └─────────────┘             │
+│         │                                                        │
+│         ▼                                                        │
+│  ┌─────────────────────────────────────────────────────────┐   │
+│  │              Browser Provider Selection                  │   │
+│  │  ┌─────────────────┐    ┌─────────────────────────┐    │   │
+│  │  │ chrome-devtools │ OR │ puppeteer.js (standalone)│    │   │
+│  │  │   (if exists)   │    │   (bundled fallback)    │    │   │
+│  │  └─────────────────┘    └─────────────────────────┘    │   │
+│  └─────────────────────────────────────────────────────────┘   │
+└─────────────────────────────────────────────────────────────────┘
+            │
+            ▼
+┌─────────────────────────────────────────────────────────────────┐
+│                    Chrome/Chromium                               │
+│  Auto-detected paths:                                            │
+│  - macOS: /Applications/Google Chrome.app/...                   │
+│  - Linux: /usr/bin/google-chrome, /usr/bin/chromium             │
+│  - Windows: C:\Program Files\Google\Chrome\...                  │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+## Component Details
+
+### 1. Browser Abstraction Layer
+
+```
+src/utils/
+├── browser.js      # Facade - auto-selects provider
+├── puppeteer.js    # Standalone Puppeteer wrapper
+├── helpers.js      # CLI utilities (parseArgs, outputJSON)
+├── env.js          # Node.js env resolution
+└── env.py          # Python env resolution
+```
+
+**browser.js** - Facade pattern for browser automation:
+```javascript
+// Auto-detects chrome-devtools skill or falls back to standalone
+async function initProvider() {
+  if (fs.existsSync(CHROME_DEVTOOLS_PATH)) {
+    browserModule = await import(CHROME_DEVTOOLS_PATH);
+    providerName = 'chrome-devtools';
+  } else {
+    browserModule = await import('./puppeteer.js');
+    providerName = 'standalone';
+  }
+}
+```
+
+**puppeteer.js** - Standalone browser wrapper:
+- Cross-platform Chrome detection (macOS, Linux, Windows)
+- Session persistence via WebSocket endpoint caching
+- PID tracking for cleanup
+
+### 2. Environment Resolution
+
+Both Node.js and Python share same resolution order:
+
+```
+1. process.env / os.environ (already set)
+2. .env in current working directory
+3. .env in skill directory
+4. .env in ~/.claude/skills/
+5. .env in ~/.claude/
+```
+
+**Cross-platform support:**
+- Windows: Uses `USERPROFILE` when `HOME` unavailable
+- Python 3.9+: Uses `List[Path]` from typing module
+
+### 3. Core Scripts
+
+| Script | Location | Language | Purpose |
+|--------|----------|----------|---------|
+| screenshot.js | src/core/ | Node.js | Screenshot capture, HTML/CSS extraction |
+| filter-css.js | src/core/ | Node.js | Remove unused CSS selectors |
+| extract-assets.js | src/core/ | Node.js | Download images, fonts, icons |
+| analyze-structure.py | src/ai/ | Python | Gemini AI structure analysis |
+| extract-design-tokens.py | src/ai/ | Python | Color, typography, spacing extraction |
+| verify-menu.js | src/verification/ | Node.js | Test responsive navigation |
+| verify-layout.js | src/verification/ | Node.js | Verify layout consistency |
+
+### 4. Post-Processing
+
+```
+src/post-process/
+├── fetch-images.js     # Fetch and optimize images
+├── inject-icons.js     # Replace icons with Font Awesome
+└── enhance-assets.js   # Enhance extracted assets
+```
+
+### 5. Progressive Disclosure
+
+SKILL.md kept concise. Detailed docs in docs/:
+
+```
+docs/
+├── basic-clone.md       # design:clone workflow
+├── pixel-perfect.md     # design:clone-px workflow
+├── cli-reference.md     # All script options
+├── design-clone-architecture.md  # This file
+└── troubleshooting.md   # Common issues
+```
+
+### 6. CLI Tool
+
+```
+bin/
+├── cli.js               # Entry point (bin: design-clone)
+├── commands/
+│   ├── init.js          # Install skill to ~/.claude/skills/
+│   ├── verify.js        # Check installation status
+│   └── help.js          # Usage information
+└── utils/
+    ├── copy.js          # Recursive file copy
+    └── validate.js      # Environment checks
+```
+
+## Data Flow
+
+### design:clone
+
+```
+URL → src/core/screenshot.js → Screenshots (3 viewports)
+                              → source.html (cleaned)
+                              → source-raw.css
+    → src/core/filter-css.js  → source.css (filtered)
+```
+
+### design:clone-px
+
+```
+URL → src/core/screenshot.js      → Screenshots + HTML/CSS
+    → src/core/filter-css.js      → Filtered CSS
+    → src/core/extract-assets.js  → assets/ (images, fonts, icons)
+    → src/ai/analyze-structure.py → structure.md (AI analysis)
+    → src/ai/extract-design-tokens.py → tokens.json, tokens.css
+    → src/verification/verify-menu.js → Menu validation report
+```
+
+## Output Structure
+
+```
+cloned-design/
+├── desktop.png           # 1920x1080
+├── tablet.png            # 768x1024
+├── mobile.png            # 375x812
+├── source.html           # Cleaned HTML
+├── source.css            # Filtered CSS
+├── source-raw.css        # Original CSS
+├── structure.md          # AI analysis (optional)
+├── tokens.json           # Design tokens
+├── tokens.css            # CSS variables
+└── assets/
+    ├── images/
+    ├── fonts/
+    └── icons/
+```
+
+## Dependencies
+
+### Node.js (package.json)
+- `css-tree`: CSS parsing and filtering
+- `puppeteer`: Browser automation (peerDep, optional)
+
+### Python (requirements.txt)
+- `google-genai`: Gemini AI for vision analysis
+
+## Installation Methods
+
+### npm (Recommended)
+```bash
+npm install -g design-clone
+design-clone init
+```
+
+### Manual
+```bash
+cp -r design-clone ~/.claude/skills/design-clone
+cd ~/.claude/skills/design-clone
+npm install && pip install -r requirements.txt
+```
+
+## Security Considerations
+
+1. **Path validation**: Prevents directory traversal
+2. **CSS sanitization**: Removes XSS vectors (expression(), javascript:)
+3. **Size limits**: 10MB max CSS input
+4. **No secrets in output**: Scripts don't expose env vars