design-clone 1.2.0 → 2.1.0

package/src/route-discoverers/universal-discoverer.js

@@ -0,0 +1,227 @@
+/**
+ * Universal Route Discoverer
+ *
+ * Fallback discoverer for unknown frameworks or static sites.
+ * Uses comprehensive techniques:
+ * - history.pushState/replaceState interception
+ * - Exhaustive link scraping from navigation elements
+ * - Sitemap.xml parsing if available
+ */
+
+import { BaseDiscoverer } from './base-discoverer.js';
+
+export class UniversalDiscoverer extends BaseDiscoverer {
+  /**
+   * Discover routes using universal techniques
+   * @returns {Promise<import('./base-discoverer.js').DiscoveredRoute[]>}
+   */
+  async discover() {
+    // First, inject history interception
+    await this.injectHistoryInterception();
+
+    // Get routes from multiple sources
+    const rawRoutes = await this.page.evaluate(() => {
+      const routes = [];
+      const seenPaths = new Set();
+
+      /**
+       * Add route if not already seen
+       */
+      function addRoute(path, name, source) {
+        if (!path || seenPaths.has(path)) return;
+        if (!path.startsWith('/')) return;
+
+        // Skip common non-page paths
+        const skipPatterns = [
+          /\.(js|css|png|jpg|jpeg|gif|svg|ico|woff|woff2|ttf|eot|map)$/i,
+          /^\/api\//,
+          /^\/_next\//,
+          /^\/_nuxt\//,
+          /^\/static\//,
+          /^\/assets\//,
+        ];
+
+        if (skipPatterns.some(pattern => pattern.test(path))) return;
+
+        seenPaths.add(path);
+        routes.push({
+          path,
+          name: name || '',
+          source
+        });
+      }
+
+      // Method 1: History interception results
+      if (window.__UNIVERSAL_DISCOVERED_ROUTES__ && Array.isArray(window.__UNIVERSAL_DISCOVERED_ROUTES__)) {
+        window.__UNIVERSAL_DISCOVERED_ROUTES__.forEach(url => {
+          try {
+            const path = new URL(url, window.location.origin).pathname;
+            addRoute(path, '', 'interception');
+          } catch {
+            // Invalid URL, skip
+          }
+        });
+      }
+
+      // Method 2: Navigation elements (high confidence)
+      const navSelectors = [
+        'nav a[href]',
+        'header a[href]',
+        '[role="navigation"] a[href]',
+        '[class*="nav"] a[href]',
+        '[class*="menu"] a[href]',
+        '[class*="sidebar"] a[href]',
+        'footer a[href]'
+      ];
+
+      navSelectors.forEach(selector => {
+        document.querySelectorAll(selector).forEach(link => {
+          const href = link.getAttribute('href');
+          if (href && href.startsWith('/')) {
+            addRoute(href, link.textContent?.trim() || '', 'link-scrape');
+          }
+        });
+      });
+
+      // Method 3: All internal links (lower confidence but comprehensive)
+      document.querySelectorAll('a[href^="/"]').forEach(link => {
+        const href = link.getAttribute('href');
+        if (href) {
+          // Skip if has target="_blank" or download attribute
+          if (link.hasAttribute('download')) return;
+          if (link.getAttribute('target') === '_blank') return;
+
+          addRoute(href, link.textContent?.trim() || '', 'link-scrape');
+        }
+      });
+
+      // Method 4: Links in main content area
+      const mainSelectors = ['main', '[role="main"]', '#content', '.content', 'article'];
+      mainSelectors.forEach(selector => {
+        const main = document.querySelector(selector);
+        if (main) {
+          main.querySelectorAll('a[href^="/"]').forEach(link => {
+            const href = link.getAttribute('href');
+            if (href && !link.hasAttribute('download')) {
+              addRoute(href, link.textContent?.trim() || '', 'link-scrape');
+            }
+          });
+        }
+      });
+
+      return routes;
+    });
+
+    // Try to fetch sitemap
+    const sitemapRoutes = await this.fetchSitemapRoutes();
+
+    // Combine all routes
+    const allRoutes = [...rawRoutes, ...sitemapRoutes];
+
+    const processedRoutes = allRoutes.map(route => ({
+      ...route,
+      name: route.name || this.extractPageName(route.path),
+      path: this.normalizeRoute(route.path)
+    }));
+
+    return this.deduplicateRoutes(processedRoutes);
+  }
+
+  /**
+   * Inject history.pushState/replaceState interception
+   */
+  async injectHistoryInterception() {
+    try {
+      await this.page.evaluate(() => {
+        if (window.__UNIVERSAL_INTERCEPTION_ACTIVE__) return;
+
+      window.__UNIVERSAL_DISCOVERED_ROUTES__ = [];
+      window.__UNIVERSAL_INTERCEPTION_ACTIVE__ = true;
+
+      // Intercept pushState
+      const originalPushState = history.pushState.bind(history);
+      history.pushState = function(state, title, url) {
+        if (url) {
+          window.__UNIVERSAL_DISCOVERED_ROUTES__.push(url.toString());
+        }
+        return originalPushState(state, title, url);
+      };
+
+      // Intercept replaceState
+      const originalReplaceState = history.replaceState.bind(history);
+      history.replaceState = function(state, title, url) {
+        if (url) {
+          window.__UNIVERSAL_DISCOVERED_ROUTES__.push(url.toString());
+        }
+        return originalReplaceState(state, title, url);
+      };
+
+      // Listen for popstate
+      window.addEventListener('popstate', () => {
+        window.__UNIVERSAL_DISCOVERED_ROUTES__.push(window.location.pathname);
+      });
+
+      // Listen for hashchange (for hash-based routing)
+      window.addEventListener('hashchange', () => {
+        window.__UNIVERSAL_DISCOVERED_ROUTES__.push(window.location.href);
+      });
+    });
+    } catch {
+      // Interception may fail in some browser contexts, continue without it
+    }
+  }
+
+  /**
+   * Try to fetch and parse sitemap.xml
+   * @returns {Promise<import('./base-discoverer.js').DiscoveredRoute[]>}
+   */
+  async fetchSitemapRoutes() {
+    const routes = [];
+
+    try {
+      const sitemapUrl = new URL('/sitemap.xml', this.baseUrl).href;
+
+      const response = await this.page.evaluate(async (url) => {
+        try {
+          // Add timeout using AbortController
+          const controller = new AbortController();
+          const timeoutId = setTimeout(() => controller.abort(), 5000);
+
+          const res = await fetch(url, { signal: controller.signal });
+          clearTimeout(timeoutId);
+
+          if (!res.ok) return null;
+          return await res.text();
+        } catch {
+          return null;
+        }
+      }, sitemapUrl);
+
+      if (response) {
+        // Parse sitemap XML
+        const urlMatches = response.matchAll(/<loc>([^<]+)<\/loc>/gi);
+        for (const match of urlMatches) {
+          try {
+            const url = new URL(match[1]);
+            // Only include paths from same origin
+            if (url.origin === new URL(this.baseUrl).origin) {
+              routes.push({
+                path: url.pathname,
+                name: '',
+                source: 'sitemap'
+              });
+            }
+          } catch {
+            // Invalid URL in sitemap
+          }
+        }
+      }
+    } catch {
+      // Sitemap fetch failed, continue without it
+    }
+
+    return routes;
+  }
+}
+
+export default UniversalDiscoverer;

package/src/route-discoverers/vue-discoverer.js

@@ -0,0 +1,118 @@
+/**
+ * Vue Route Discoverer
+ *
+ * Extracts routes from Vue 2 and Vue 3 applications using:
+ * - Vue 3: app.__vue_app__.$router
+ * - Vue 2: window.Vue.prototype.$router
+ * - Fallback: data-v-* attributes and router-link elements
+ */
+
+import { BaseDiscoverer } from './base-discoverer.js';
+
+export class VueDiscoverer extends BaseDiscoverer {
+  /**
+   * Discover routes from a Vue application
+   * @returns {Promise<import('./base-discoverer.js').DiscoveredRoute[]>}
+   */
+  async discover() {
+    const rawRoutes = await this.page.evaluate(() => {
+      const routes = [];
+
+      /**
+       * Recursively extract routes from Vue Router config
+       */
+      function extractRoutes(routeList, prefix = '') {
+        if (!Array.isArray(routeList)) return;
+
+        routeList.forEach(r => {
+          if (!r.path && r.path !== '') return;
+
+          let path = r.path;
+          if (!path.startsWith('/') && prefix) {
+            path = prefix + (prefix.endsWith('/') ? '' : '/') + path;
+          } else if (!path.startsWith('/') && path !== '') {
+            path = '/' + path;
+          }
+
+          // Handle root path
+          if (path === '') path = '/';
+
+          routes.push({
+            path,
+            name: r.name || '',
+            component: r.component?.name || r.name || '',
+            source: 'framework'
+          });
+
+          if (r.children) {
+            extractRoutes(r.children, path);
+          }
+        });
+      }
+
+      // Method 1: Vue 3 - __vue_app__ on root element
+      const appElements = document.querySelectorAll('[data-v-app], #app, #__nuxt');
+      for (const el of appElements) {
+        const vueApp = el.__vue_app__;
+        if (vueApp?.config?.globalProperties?.$router?.options?.routes) {
+          extractRoutes(vueApp.config.globalProperties.$router.options.routes);
+          break;
+        }
+      }
+
+      // Method 2: Vue 2 - window.Vue.prototype.$router
+      if (routes.length === 0 && window.Vue?.prototype?.$router?.options?.routes) {
+        extractRoutes(window.Vue.prototype.$router.options.routes);
+      }
+
+      // Method 3: __VUE_ROUTER__ global (some configurations)
+      if (routes.length === 0 && window.__VUE_ROUTER__?.options?.routes) {
+        extractRoutes(window.__VUE_ROUTER__.options.routes);
+      }
+
+      // Method 4: router-link elements
+      document.querySelectorAll('router-link, a[href]').forEach(link => {
+        let href = link.getAttribute('to') || link.getAttribute('href');
+        if (href && href.startsWith('/')) {
+          const text = link.textContent?.trim();
+          const isVueComponent = link.tagName.toLowerCase() === 'router-link' ||
+                                link.closest('[data-v-]');
+
+          if (!routes.some(r => r.path === href)) {
+            routes.push({
+              path: href,
+              name: text || '',
+              source: isVueComponent ? 'framework' : 'link-scrape'
+            });
+          }
+        }
+      });
+
+      // Method 5: Links with data-v-* attributes (scoped styles indicate Vue components)
+      if (routes.length === 0) {
+        document.querySelectorAll('nav a, header a, [role="navigation"] a').forEach(link => {
+          const href = link.getAttribute('href');
+          if (href && href.startsWith('/')) {
+            routes.push({
+              path: href,
+              name: link.textContent?.trim() || '',
+              source: 'link-scrape'
+            });
+          }
+        });
+      }
+
+      return routes;
+    });
+
+    const processedRoutes = rawRoutes.map(route => ({
+      ...route,
+      name: route.name || this.extractPageName(route.path, route.component),
+      path: this.normalizeRoute(route.path)
+    }));
+
+    return this.deduplicateRoutes(processedRoutes);
+  }
+}
+
+export default VueDiscoverer;

package/src/utils/__init__.py

@@ -3,7 +3,7 @@ Design Clone skill library modules.
 
 JavaScript modules:
 - browser.js: Browser abstraction facade
-- puppeteer.js: Standalone Puppeteer wrapper
+- playwright.js: Playwright browser wrapper
 - utils.js: CLI utilities
 - env.js: Environment variable resolution
 

package/src/utils/browser.js

@@ -1,11 +1,9 @@
 /**
  * Browser abstraction facade for design-clone scripts
  *
- * Auto-detects and uses:
- * 1. chrome-devtools skill (if installed) - Preferred
- * 2. Standalone puppeteer wrapper - Fallback
+ * Uses Playwright wrapper for browser automation.
  *
- * Exports same API regardless of provider:
+ * Exports same API:
  * - getBrowser(options)
  * - getPage(browser)
  * - closeBrowser()
@@ -15,18 +13,6 @@
  * - 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';
 
@@ -36,22 +22,9 @@ let providerName = 'unknown';
 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');
+  browserModule = await import('./playwright.js');
+  providerName = 'playwright';
+  console.error('[browser] Using Playwright wrapper');
 }
 
 // Import utilities (always use local helpers)
@@ -60,7 +33,7 @@ export { parseArgs, outputJSON, outputError };
 
 /**
  * Get current browser provider name
- * @returns {string} 'chrome-devtools' or 'standalone'
+ * @returns {string} 'playwright'
  */
 export function getProviderName() {
   return providerName;
@@ -79,15 +52,16 @@ export async function getBrowser(options = {}) {
 /**
  * Get page from browser
  * @param {Browser} browser - Browser instance
+ * @param {Object} [options] - Page options
  * @returns {Promise<Page>} Page instance
  */
-export async function getPage(browser) {
+export async function getPage(browser, options = {}) {
   await initProvider();
-  return browserModule.getPage(browser);
+  return browserModule.getPage(browser, options);
 }
 
 /**
- * Close browser and clear session
+ * Close browser
  */
 export async function closeBrowser() {
   await initProvider();
@@ -95,7 +69,7 @@ export async function closeBrowser() {
 }
 
 /**
- * Disconnect from browser without closing
+ * Disconnect from browser (alias for close in Playwright)
  */
 export async function disconnectBrowser() {
   await initProvider();

package/src/utils/playwright.js

@@ -0,0 +1,213 @@
+/**
+ * Standalone Playwright browser wrapper for design-clone scripts
+ * Provides browser automation with Playwright
+ *
+ * Features:
+ * - Auto-detects Chrome installation path (macOS, Linux, Windows)
+ * - Fast browser launch (no session persistence needed)
+ * - Compatible API with previous Puppeteer wrapper
+ */
+
+import fs from 'fs';
+
+/** @type {import('playwright').Browser|null} */
+let browserInstance = null;
+/** @type {import('playwright').Page|null} */
+let pageInstance = null;
+/** @type {typeof import('playwright')|null} */
+let playwright = null;
+
+/** Default viewport dimensions */
+const DEFAULT_VIEWPORT = { width: 1920, height: 1080 };
+
+/**
+ * Detect Chrome executable path by platform
+ * Used for playwright-core fallback when full playwright is not installed
+ * @returns {string|null} Chrome path or null if not found
+ */
+function detectChromePath() {
+  const platform = process.platform;
+
+  const paths = {
+    darwin: [
+      '/Applications/Google Chrome.app/Contents/MacOS/Google Chrome',
+      '/Applications/Chromium.app/Contents/MacOS/Chromium',
+      '/Applications/Google Chrome Canary.app/Contents/MacOS/Google Chrome Canary'
+    ],
+    linux: [
+      '/usr/bin/google-chrome',
+      '/usr/bin/google-chrome-stable',
+      '/usr/bin/chromium',
+      '/usr/bin/chromium-browser',
+      '/snap/bin/chromium'
+    ],
+    win32: [
+      'C:\\Program Files\\Google\\Chrome\\Application\\chrome.exe',
+      'C:\\Program Files (x86)\\Google\\Chrome\\Application\\chrome.exe',
+      ...(process.env.LOCALAPPDATA ? [`${process.env.LOCALAPPDATA}\\Google\\Chrome\\Application\\chrome.exe`] : [])
+    ]
+  };
+
+  const candidates = paths[platform] || [];
+  for (const chromePath of candidates) {
+    if (fs.existsSync(chromePath)) {
+      return chromePath;
+    }
+  }
+
+  return null;
+}
+
+/**
+ * Load playwright module (try playwright first, then playwright-core)
+ * @returns {Promise<Object>} Playwright module with chromium browser type
+ * @throws {Error} If neither playwright nor playwright-core is installed
+ */
+async function loadPlaywright() {
+  if (playwright) return playwright;
+
+  try {
+    // Try full playwright first (includes bundled browsers)
+    playwright = await import('playwright');
+    return playwright;
+  } catch (e1) {
+    try {
+      // Fall back to playwright-core (requires Chrome)
+      playwright = await import('playwright-core');
+      return playwright;
+    } catch (e2) {
+      throw new Error(
+        'Playwright not found. Install with: npm install playwright\n' +
+        'Or for smaller install: npm install playwright-core\n' +
+        `Details: playwright: ${e1.message}, playwright-core: ${e2.message}`
+      );
+    }
+  }
+}
+
+/**
+ * Launch browser instance
+ *
+ * @param {Object} options - Browser options
+ * @param {boolean} [options.headless=true] - Run in headless mode
+ * @param {Object} [options.viewport] - Default viewport dimensions (applied per context)
+ * @param {string} [options.executablePath] - Chrome executable path override
+ * @param {string[]} [options.args] - Additional Chrome arguments
+ * @returns {Promise<Browser>} Playwright browser instance
+ * @throws {Error} If Chrome not found and no executablePath provided (playwright-core)
+ */
+export async function getBrowser(options = {}) {
+  const pw = await loadPlaywright();
+
+  // Reuse existing browser if connected
+  if (browserInstance && browserInstance.isConnected()) {
+    return browserInstance;
+  }
+
+  // Determine executable path for playwright-core
+  let executablePath = options.executablePath;
+  if (!executablePath) {
+    // Check if we're using playwright-core (no bundled browser)
+    const isCore = !pw.chromium?.executablePath;
+    if (isCore) {
+      executablePath = detectChromePath();
+      if (!executablePath) {
+        throw new Error(
+          'Chrome not found. Either:\n' +
+          '1. Install Google Chrome\n' +
+          '2. Use full playwright (npm install playwright)\n' +
+          '3. Set executablePath option'
+        );
+      }
+    }
+  }
+
+  // Build launch options
+  const launchOptions = {
+    headless: options.headless !== false,
+    args: [
+      '--no-sandbox',
+      '--disable-setuid-sandbox',
+      '--disable-dev-shm-usage',
+      ...(options.args || [])
+    ]
+  };
+
+  // Only set executablePath if needed (playwright-core or override)
+  if (executablePath) {
+    launchOptions.executablePath = executablePath;
+  }
+
+  // Launch browser
+  browserInstance = await pw.chromium.launch(launchOptions);
+  console.error('[browser] Launched Playwright browser');
+
+  return browserInstance;
+}
+
+/**
+ * Get current page or create new one
+ * Reuses existing page if available
+ *
+ * @param {import('playwright').Browser} browser - Playwright browser instance
+ * @param {Object} [options] - Page options
+ * @param {{width: number, height: number}} [options.viewport] - Viewport dimensions
+ * @returns {Promise<import('playwright').Page>} Playwright page instance
+ * @throws {Error} If browser is null or disconnected
+ */
+export async function getPage(browser, options = {}) {
+  if (!browser || !browser.isConnected()) {
+    throw new Error('Browser not connected. Call getBrowser() first.');
+  }
+
+  if (pageInstance && !pageInstance.isClosed()) {
+    return pageInstance;
+  }
+
+  // Get existing pages or create new context + page
+  const contexts = browser.contexts();
+  if (contexts.length > 0) {
+    const pages = contexts[0].pages();
+    if (pages.length > 0) {
+      pageInstance = pages[0];
+      return pageInstance;
+    }
+  }
+
+  // Create new context with default viewport
+  const contextOptions = {
+    viewport: options.viewport || DEFAULT_VIEWPORT
+  };
+
+  const context = await browser.newContext(contextOptions);
+  pageInstance = await context.newPage();
+
+  return pageInstance;
+}
+
+/**
+ * Close browser
+ * Use when completely done with browser
+ */
+export async function closeBrowser() {
+  if (browserInstance) {
+    try {
+      await browserInstance.close();
+    } catch (err) {
+      console.error(`[browser] Error closing browser: ${err.message}`);
+    }
+    browserInstance = null;
+    pageInstance = null;
+    console.error('[browser] Closed browser');
+  }
+}
+
+/**
+ * Disconnect from browser (alias for closeBrowser in Playwright)
+ * Playwright doesn't support disconnect without close, so this is an alias
+ */
+export async function disconnectBrowser() {
+  // Playwright doesn't have disconnect concept like Puppeteer
+  // Just close the browser for API compatibility
+  return closeBrowser();
+}