design-clone 1.0.0

package/src/utils/__init__.py

@@ -0,0 +1,16 @@
+"""
+Design Clone skill library modules.
+
+JavaScript modules:
+- browser.js: Browser abstraction facade
+- puppeteer.js: Standalone Puppeteer wrapper
+- utils.js: CLI utilities
+- env.js: Environment variable resolution
+
+Python modules:
+- env.py: Environment variable resolution
+"""
+
+from .env import resolve_env, load_env, require_env, get_skill_dir
+
+__all__ = ['resolve_env', 'load_env', 'require_env', 'get_skill_dir']

package/src/utils/browser.js

@@ -0,0 +1,103 @@
+/**
+ * Browser abstraction facade for design-clone scripts
+ *
+ * Auto-detects and uses:
+ * 1. chrome-devtools skill (if installed) - Preferred
+ * 2. Standalone puppeteer wrapper - Fallback
+ *
+ * Exports same API regardless of provider:
+ * - getBrowser(options)
+ * - getPage(browser)
+ * - closeBrowser()
+ * - disconnectBrowser()
+ * - parseArgs(argv)
+ * - outputJSON(data)
+ * - outputError(error)
+ */
+
+import fs from 'fs';
+import path from 'path';
+import { fileURLToPath } from 'url';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+// Chrome DevTools skill path
+const CHROME_DEVTOOLS_PATH = path.join(
+  process.env.HOME,
+  '.claude/skills/chrome-devtools/scripts/lib/browser.js'
+);
+
+let browserModule = null;
+let providerName = 'unknown';
+
+/**
+ * Initialize browser provider (lazy-loaded)
+ */
+async function initProvider() {
+  if (browserModule) return;
+
+  // Check for chrome-devtools skill
+  if (fs.existsSync(CHROME_DEVTOOLS_PATH)) {
+    try {
+      browserModule = await import(CHROME_DEVTOOLS_PATH);
+      providerName = 'chrome-devtools';
+      console.error('[browser] Using chrome-devtools skill');
+      return;
+    } catch (e) {
+      console.error('[browser] chrome-devtools found but failed to load:', e.message);
+    }
+  }
+
+  // Fall back to standalone puppeteer wrapper
+  browserModule = await import('./puppeteer.js');
+  providerName = 'standalone';
+  console.error('[browser] Using standalone puppeteer wrapper');
+}
+
+// Import utilities (always use local helpers)
+import { parseArgs, outputJSON, outputError } from './helpers.js';
+export { parseArgs, outputJSON, outputError };
+
+/**
+ * Get current browser provider name
+ * @returns {string} 'chrome-devtools' or 'standalone'
+ */
+export function getProviderName() {
+  return providerName;
+}
+
+/**
+ * Launch or connect to browser
+ * @param {Object} options - Browser options
+ * @returns {Promise<Browser>} Browser instance
+ */
+export async function getBrowser(options = {}) {
+  await initProvider();
+  return browserModule.getBrowser(options);
+}
+
+/**
+ * Get page from browser
+ * @param {Browser} browser - Browser instance
+ * @returns {Promise<Page>} Page instance
+ */
+export async function getPage(browser) {
+  await initProvider();
+  return browserModule.getPage(browser);
+}
+
+/**
+ * Close browser and clear session
+ */
+export async function closeBrowser() {
+  await initProvider();
+  return browserModule.closeBrowser();
+}
+
+/**
+ * Disconnect from browser without closing
+ */
+export async function disconnectBrowser() {
+  await initProvider();
+  return browserModule.disconnectBrowser();
+}

package/src/utils/env.js

@@ -0,0 +1,153 @@
+/**
+ * Environment variable resolution for design-clone scripts
+ *
+ * Search order (first found wins, process.env takes precedence):
+ * 1. process.env (already set)
+ * 2. .env in current working directory
+ * 3. .env in skill directory (scripts/design-clone/)
+ * 4. .env in ~/.claude/skills/
+ * 5. .env in ~/.claude/
+ *
+ * @module lib/env
+ */
+
+import fs from 'fs';
+import path from 'path';
+import { fileURLToPath } from 'url';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+// From src/utils/ -> go up 2 levels to reach skill root (design-clone/)
+const SKILL_DIR = path.resolve(__dirname, '../..');
+
+/**
+ * Get user home directory (cross-platform: HOME on Unix, USERPROFILE on Windows)
+ * @returns {string} Home directory path
+ */
+function getHomeDir() {
+  return process.env.HOME || process.env.USERPROFILE || '';
+}
+
+/**
+ * Get list of .env file search paths
+ * @returns {string[]} Array of directory paths to search for .env
+ */
+function getEnvSearchPaths() {
+  const home = getHomeDir();
+  return [
+    process.cwd(),
+    SKILL_DIR,
+    home ? path.join(home, '.claude/skills') : null,
+    home ? path.join(home, '.claude') : null
+  ].filter(Boolean);
+}
+
+/**
+ * Parse .env file content into key-value object
+ * Handles: KEY=value, KEY="quoted value", KEY='quoted', comments (#), empty lines
+ * Quote handling: Only strips matching outer quotes (both same type, length >= 2)
+ *
+ * @param {string} content - .env file content
+ * @returns {Object} Parsed key-value pairs
+ */
+function parseEnvContent(content) {
+  const result = {};
+
+  content.split('\n').forEach(line => {
+    // Skip empty lines and comments
+    const trimmed = line.trim();
+    if (!trimmed || trimmed.startsWith('#')) return;
+
+    // Parse KEY=value using partition approach (handles = in value)
+    const eqIndex = trimmed.indexOf('=');
+    if (eqIndex === -1) return;
+
+    const key = trimmed.slice(0, eqIndex).trim();
+    if (!key) return;
+
+    let value = trimmed.slice(eqIndex + 1).trim();
+
+    // Remove matching outer quotes only (double or single)
+    // Must have same quote type at both ends, length >= 2
+    if (value.length >= 2) {
+      const first = value[0];
+      const last = value[value.length - 1];
+      if ((first === '"' && last === '"') || (first === "'" && last === "'")) {
+        value = value.slice(1, -1);
+      }
+    }
+
+    result[key] = value;
+  });
+
+  return result;
+}
+
+/**
+ * Load environment variables from .env files
+ * Only sets variables not already in process.env
+ *
+ * @returns {string|null} Path to loaded .env file, or null if none found
+ */
+export function loadEnv() {
+  const searchPaths = getEnvSearchPaths();
+
+  for (const dir of searchPaths) {
+    const envPath = path.join(dir, '.env');
+
+    if (fs.existsSync(envPath)) {
+      try {
+        const content = fs.readFileSync(envPath, 'utf-8');
+        const parsed = parseEnvContent(content);
+
+        // Only set vars not already in process.env
+        Object.entries(parsed).forEach(([key, value]) => {
+          if (!process.env[key]) {
+            process.env[key] = value;
+          }
+        });
+
+        return envPath;
+      } catch (err) {
+        console.error(`[env] Failed to read ${envPath}: ${err.message}`);
+      }
+    }
+  }
+
+  return null;
+}
+
+/**
+ * Get environment variable with optional default
+ *
+ * @param {string} key - Environment variable name
+ * @param {string} [defaultValue=null] - Default value if not found
+ * @returns {string|null} Variable value or default
+ */
+export function getEnv(key, defaultValue = null) {
+  return process.env[key] || defaultValue;
+}
+
+/**
+ * Require environment variable, throw if not found
+ *
+ * @param {string} key - Environment variable name
+ * @param {string} [hint] - Hint message for how to set the variable
+ * @returns {string} Variable value
+ * @throws {Error} If variable not set
+ */
+export function requireEnv(key, hint = '') {
+  const value = process.env[key];
+  if (!value) {
+    const hintMsg = hint ? `\nHint: ${hint}` : '';
+    throw new Error(`Required environment variable ${key} not set.${hintMsg}`);
+  }
+  return value;
+}
+
+/**
+ * Get skill directory path
+ * @returns {string} Absolute path to skill directory
+ */
+export function getSkillDir() {
+  return SKILL_DIR;
+}

package/src/utils/env.py

@@ -0,0 +1,134 @@
+"""
+Environment variable resolution for design-clone scripts.
+
+Search order (first found wins, os.environ takes precedence):
+1. os.environ (already set)
+2. .env in current working directory
+3. .env in skill directory (scripts/design-clone/)
+4. .env in ~/.claude/skills/
+5. .env in ~/.claude/
+
+Usage:
+    from lib.env import resolve_env, load_env, get_skill_dir
+
+    # Load all .env files
+    load_env()
+
+    # Get specific variable with fallback
+    api_key = resolve_env('GEMINI_API_KEY', default=None)
+"""
+
+import os
+from pathlib import Path
+from typing import Dict, List, Optional
+
+# Skill directory - from src/utils/ go up 2 levels to reach design-clone/
+SKILL_DIR = Path(__file__).parent.parent.parent.resolve()
+
+
+def get_env_search_paths() -> List[Path]:
+    """Get list of directories to search for .env files."""
+    return [
+        Path.cwd(),
+        SKILL_DIR,
+        Path.home() / '.claude' / 'skills',
+        Path.home() / '.claude'
+    ]
+
+
+def parse_env_file(file_path: Path) -> Dict[str, str]:
+    """
+    Parse .env file into key-value dict.
+    Handles: KEY=value, KEY="quoted value", comments (#), empty lines
+    """
+    result = {}
+
+    try:
+        with open(file_path, 'r', encoding='utf-8') as f:
+            for line in f:
+                line = line.strip()
+
+                # Skip empty lines and comments
+                if not line or line.startswith('#'):
+                    continue
+
+                # Parse KEY=value
+                if '=' in line:
+                    key, _, value = line.partition('=')
+                    key = key.strip()
+                    value = value.strip()
+
+                    # Remove quotes if present
+                    if (value.startswith('"') and value.endswith('"')) or \
+                       (value.startswith("'") and value.endswith("'")):
+                        value = value[1:-1]
+
+                    result[key] = value
+    except Exception as e:
+        print(f"[env] Failed to read {file_path}: {e}")
+
+    return result
+
+
+def load_env() -> Optional[Path]:
+    """
+    Load environment variables from .env files.
+    Only sets variables not already in os.environ.
+
+    Returns:
+        Path to loaded .env file, or None if none found.
+    """
+    for dir_path in get_env_search_paths():
+        env_file = dir_path / '.env'
+
+        if env_file.exists():
+            parsed = parse_env_file(env_file)
+
+            # Only set vars not already in environ
+            for key, value in parsed.items():
+                if key not in os.environ:
+                    os.environ[key] = value
+
+            return env_file
+
+    return None
+
+
+def resolve_env(key: str, default: Optional[str] = None) -> Optional[str]:
+    """
+    Get environment variable with optional default.
+
+    Args:
+        key: Environment variable name
+        default: Default value if not found
+
+    Returns:
+        Variable value or default
+    """
+    return os.environ.get(key, default)
+
+
+def require_env(key: str, hint: str = '') -> str:
+    """
+    Require environment variable, raise if not found.
+
+    Args:
+        key: Environment variable name
+        hint: Hint message for how to set the variable
+
+    Returns:
+        Variable value
+
+    Raises:
+        OSError: If variable not set
+    """
+    value = os.environ.get(key)
+    if not value:
+        hint_msg = f'\nHint: {hint}' if hint else ''
+        raise OSError(f'Required environment variable {key} not set.{hint_msg}')
+    return value
+
+
+def get_skill_dir() -> Path:
+    """Get skill directory path."""
+    return SKILL_DIR

package/src/utils/helpers.js

@@ -0,0 +1,71 @@
+/**
+ * Shared utility functions for design-clone scripts
+ * Provides CLI parsing and JSON output helpers
+ */
+
+/**
+ * Parse command line arguments into key-value object
+ * @param {string[]} argv - Command line arguments
+ * @returns {Object} Parsed arguments
+ * @throws {TypeError} If argv is not an array
+ *
+ * @example
+ * parseArgs(['--url', 'https://example.com', '--headless', '--port', '9222'])
+ * // Returns: { url: 'https://example.com', headless: true, port: '9222' }
+ */
+export function parseArgs(argv) {
+  // Input validation
+  if (!Array.isArray(argv)) {
+    throw new TypeError('argv must be an array');
+  }
+
+  const args = {};
+
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+
+    // Skip non-string arguments
+    if (typeof arg !== 'string') continue;
+
+    if (arg.startsWith('--')) {
+      const key = arg.slice(2);
+      const nextArg = argv[i + 1];
+
+      // If next arg exists and doesn't start with --, use it as value
+      if (nextArg && typeof nextArg === 'string' && !nextArg.startsWith('--')) {
+        args[key] = nextArg;
+        i++; // Skip next arg
+      } else {
+        // Boolean flag
+        args[key] = true;
+      }
+    }
+  }
+
+  return args;
+}
+
+/**
+ * Output data as formatted JSON to stdout
+ * @param {Object} data - Data to output
+ */
+export function outputJSON(data) {
+  console.log(JSON.stringify(data, null, 2));
+}
+
+/**
+ * Output error as JSON to stderr and exit
+ * @param {Error} error - Error object
+ * @throws {never} Always exits the process
+ */
+export function outputError(error) {
+  const errorMessage = error instanceof Error ? error.message : String(error);
+  const errorStack = error instanceof Error ? error.stack : undefined;
+
+  console.error(JSON.stringify({
+    success: false,
+    error: errorMessage,
+    stack: process.env.DEBUG ? errorStack : undefined
+  }, null, 2));
+  process.exit(1);
+}