design-clone 2.1.0 → 3.0.0

package/docs/project-roadmap.md

@@ -1,382 +0,0 @@
-# Design Clone Project Roadmap
-
-**Last Updated:** 2026-02-04
-**Current Status:** In Progress (Phase 2/3 Complete)
-**Overall Progress:** 66% (8/12 hours estimated effort completed)
-
-## Executive Summary
-
-Design Clone is an AI-powered website cloning tool with enhanced verification, UX audit, and semantic HTML capabilities. Phase 2 (UX Audit Integration) is now complete with production-ready code and comprehensive testing.
-
-## Project Phases
-
-### Phase 1: Component Verification
-**Status:** ✅ COMPLETE
-**Completed:** 2026-02-04T14:33:00Z
-**Effort:** 5h
-**Progress:** 100%
-
-#### Deliverables
-- [x] Component verifiers (header, footer, slider detection)
-- [x] Visual diff generation (Playwright screenshots, side-by-side layout)
-- [x] Audit report generation (Markdown format with checklist)
-- [x] Verification test suite (20+ tests)
-
-#### Key Files
-- `src/verification/verify-header.js` - Header structure validation
-- `src/verification/verify-footer.js` - Footer verification
-- `src/verification/verify-slider.js` - Carousel/slider detection
-- `src/verification/generate-audit-report.js` - Report generation
-- `tests/test-verification.js` - Comprehensive tests
-
-#### Success Criteria Met
-- [x] All verifiers run standalone: `node verify-header.js --url <url>`
-- [x] Audit report generated with actionable checklist
-- [x] No breaking changes to existing clone workflow
-- [x] Visual diff with clear original vs cloned comparison
-
----
-
-### Phase 2: UX Audit Integration
-**Status:** ✅ COMPLETE
-**Completed:** 2026-02-04T14:56:00Z
-**Effort:** 3h
-**Progress:** 100%
-
-#### Deliverables
-- [x] UX audit prompt definition (src/ai/prompts/ux_audit.py)
-- [x] UX audit runner (src/ai/ux-audit.js) with Gemini Vision integration
-- [x] CLI flag integration (--ux-audit)
-- [x] Report generation (analysis/ux-audit.md)
-- [x] Comprehensive test suite (20/20 tests passing)
-
-#### Key Files
-- `src/ai/prompts/ux_audit.py` - 199 lines, UX evaluation criteria
-- `src/ai/ux-audit.js` - 594 lines, Gemini integration and report generation
-- `bin/commands/clone-site.js` - Updated with --ux-audit flag
-- `tests/test-ux-audit.js` - 361 lines, 20 unit tests
-- `package.json` - Added @google/generative-ai to optionalDependencies
-
-#### Success Criteria Met
-- [x] `design-clone clone-site <url> --ux-audit` generates audit report
-- [x] Report includes scores for 6 categories (visual hierarchy, navigation, typography, spacing, interactivity, responsive)
-- [x] Issues list with severity levels (critical, major, minor) and suggested fixes
-- [x] Report generated in <10s (3 viewport analysis: desktop, tablet, mobile)
-- [x] Graceful degradation if GEMINI_API_KEY not set
-- [x] Follows existing architecture patterns (verify-layout.js Gemini integration)
-- [x] Excellent test coverage (20/20 passing)
-- [x] Code review score: 9/10
-
-#### UX Audit Features
-- **Category Analysis:** Visual hierarchy, navigation, typography, spacing, interactive elements, responsive design
-- **Severity Levels:** Critical, major, minor issue classification
-- **Multi-viewport:** Analyzes desktop, tablet, and mobile viewports
-- **Actionable Output:** Specific recommendations for improvement
-- **Error Handling:** Graceful degradation with clear user feedback
-
-#### Review & Code Quality
-- Code Review Score: 9/10
-- All tests passing: 20/20 (unit tests) + 82/82 (full suite)
-- Architecture alignment: Excellent (follows verify-layout.js patterns)
-- Security: Best practices followed
-- Documentation: Complete with examples
-
-#### Recommendations for Future
-1. Document `@google/generative-ai` dependency in README
-2. Consider consolidating prompt definitions (py/js)
-3. Add API response caching for dev workflows
-4. Monitor Gemini API rate limits in production
-
----
-
-### Phase 3: WordPress Semantic HTML
-**Status:** 🔄 NOT STARTED
-**Expected Start:** 2026-02-04 (after Phase 2 complete)
-**Estimated Effort:** 4h
-**Expected Progress:** 0%
-
-#### Planned Deliverables
-- [ ] Semantic HTML enhancer (semantic-enhancer.js)
-- [ ] WordPress-compatible landmark detection
-- [ ] HTML extraction update (html-extractor.js)
-- [ ] W3C landmark validation
-- [ ] Test suite with semantic validation
-
-#### Key Files (Planned)
-- `src/core/semantic-enhancer.js` - Landmark injection without style breaking
-- `src/core/html-extractor.js` - Update for semantic support
-- `tests/test-semantic-enhancer.js` - Semantic validation tests
-
-#### Architecture Notes
-- Reuses `dom-tree-analyzer.js` landmark detection
-- Adds IDs/classes alongside original classes (preserves styling)
-- Targets common WordPress patterns (nav, main, footer, etc.)
-- Graceful degradation if DOM structure differs
-
-#### Success Criteria (Target)
-- [ ] Semantic HTML passes W3C landmark validation
-- [ ] No breaking changes to existing clone workflow
-- [ ] Performance impact <500ms per page
-- [ ] Works with WordPress and custom themes
-
----
-
-## Timeline
-
-| Date | Milestone | Status |
-|------|-----------|--------|
-| 2026-02-04 | Phase 1 Component Verification | ✅ COMPLETE |
-| 2026-02-04 | Phase 2 UX Audit Integration | ✅ COMPLETE |
-| 2026-02-04 | Phase 3 Planning | 🔄 IN PROGRESS |
-| 2026-02-05 | Phase 3 Implementation | ⏳ PLANNED |
-| 2026-02-05 | Full Test Suite Integration | ⏳ PLANNED |
-| 2026-02-06 | Documentation Updates | ⏳ PLANNED |
-| 2026-02-06 | Code Review & QA | ⏳ PLANNED |
-| 2026-02-07 | Release Preparation | ⏳ PLANNED |
-
----
-
-## Architecture Overview
-
-### Component Stack
-
-```
-design-clone/
-├── bin/commands/
-│   ├── clone.js              (Main entry point)
-│   └── clone-site.js         (Site-specific cloning with --ux-audit flag)
-│
-├── src/
-│   ├── verification/         (Phase 1)
-│   │   ├── verify-header.js
-│   │   ├── verify-footer.js
-│   │   ├── verify-slider.js
-│   │   └── generate-audit-report.js
-│   │
-│   ├── ai/                   (Phase 2)
-│   │   ├── prompts/
-│   │   │   └── ux_audit.py
-│   │   ├── ux-audit.js
-│   │   └── analyze-structure.py
-│   │
-│   └── core/                 (Phase 3 - Planned)
-│       ├── semantic-enhancer.js
-│       ├── html-extractor.js
-│       └── dom-tree-analyzer.js
-│
-├── tests/
-│   ├── test-verification.js  (Phase 1)
-│   ├── test-ux-audit.js      (Phase 2)
-│   └── test-semantic.js      (Phase 3 - Planned)
-│
-└── analysis/
-    ├── visual-diffs/         (Phase 1 outputs)
-    ├── audit-reports/        (Phase 1 outputs)
-    └── ux-audit.md          (Phase 2 outputs)
-```
-
-### Integration Points
-
-1. **CLI Entry Point:** `bin/commands/clone-site.js`
-   - Detects `--ux-audit` flag
-   - Routes to Phase 2 UX audit runner
-
-2. **Screenshot Pipeline:**
-   - Playwright generates screenshots (desktop, tablet, mobile)
-   - Passed to Gemini Vision API for analysis
-   - Results aggregated into markdown report
-
-3. **Report Generation:**
-   - Each phase generates independent reports
-   - Reports stored in `analysis/` directory
-   - Can be combined for comprehensive site analysis
-
----
-
-## Risks & Mitigations
-
-| Risk | Phase | Impact | Mitigation |
-|------|-------|--------|-----------|
-| Slider framework variations | 1 | Medium | Focus common patterns; graceful degradation |
-| Semantic injection breaks styles | 3 | High | Add classes only, preserve originals; extensive testing |
-| Gemini API rate limits | 2 | Medium | Cache responses, batch viewport analysis |
-| Inconsistent UX scores | 2 | Low | Structured prompt, JSON schema validation |
-| API response parsing failures | 2 | Low | Regex fallback, comprehensive error handling |
-| DOM structure variations | 3 | Medium | Pattern matching, fallback to generic landmarks |
-
----
-
-## Testing Strategy
-
-### Test Coverage
-
-| Phase | Unit Tests | Integration Tests | E2E Tests |
-|-------|------------|------------------|-----------|
-| 1 | ✅ Complete | ✅ In progress | ⏳ Planned |
-| 2 | ✅ Complete (20/20) | ✅ Complete | ⏳ Planned |
-| 3 | ⏳ Planned | ⏳ Planned | ⏳ Planned |
-
-### Current Test Results
-- **Phase 1:** 20+ verification tests
-- **Phase 2:** 20/20 UX audit tests passing
-- **Full Suite:** 82/82 tests passing
-
----
-
-## Dependencies & Requirements
-
-### External Services
-- **Gemini API:** Required for UX audit analysis (Phase 2)
-  - Model: `gemini-2.5-flash`
-  - Authentication: `GEMINI_API_KEY` environment variable
-  - Fallback behavior: Graceful degradation if key not set
-
-### NPM Packages
-- `@google/generative-ai` - Optional dependency for Phase 2
-- `playwright` - For screenshot generation
-- Existing: `puppeteer`, `axios`, etc.
-
-### System Requirements
-- Node.js 16+
-- 100MB+ disk space for analysis outputs
-- API rate limits for Gemini (handled via batch processing)
-
----
-
-## Performance Metrics
-
-| Task | Target | Phase 1 | Phase 2 | Phase 3 |
-|------|--------|---------|---------|---------|
-| Single page clone | <30s | ✅ Met | ✅ Met | TBD |
-| Screenshot generation | <10s | ✅ 8s | ✅ 8s | TBD |
-| Gemini API call | <5s/viewport | N/A | ✅ 4s avg | N/A |
-| Report generation | <5s | ✅ 2s | ✅ 3s | TBD |
-| Total with audit | <60s | ✅ 30s | ✅ 45s | TBD |
-
----
-
-## Success Metrics
-
-### Phase 1: ✅ ACHIEVED
-- Component verification accuracy: 95%+
-- Audit report completeness: 100%
-- Zero breaking changes: ✅
-- Test coverage: 100% for verification module
-
-### Phase 2: ✅ ACHIEVED
-- UX audit availability: 100% when API key set
-- Category analysis completeness: 6/6 categories
-- Issue detection accuracy: 90%+
-- Report generation time: 3-5s
-- Test coverage: 20/20 passing
-
-### Phase 3: IN PROGRESS
-- Semantic HTML validation: W3C compliant (target)
-- Style preservation: 100% (target)
-- Performance impact: <500ms (target)
-- Compatibility: WordPress + custom themes (target)
-
----
-
-## Known Issues & Limitations
-
-### Phase 2
-1. **Gemini API Rate Limits:** Implement caching for development workflows
-2. **Score Consistency:** Minor variance in scores between API calls (expected)
-3. **Complex Layouts:** May not detect all interactive elements in complex SPAs
-4. **Dark Mode:** Only analyzes default viewport appearance
-
-### Future Phases
-- Semantic injection not yet implemented (Phase 3)
-- No custom rule support yet
-- Limited to web-based analysis (no PDF output)
-
----
-
-## Next Steps
-
-### Immediate (This Week)
-1. **Phase 3 Implementation:** Start WordPress semantic HTML enhancement
-2. **Documentation:** Update CLI reference with --ux-audit examples
-3. **Monitoring:** Set up API usage tracking for Gemini
-
-### Short Term (Next Sprint)
-1. Review Phase 3 integration points
-2. Set up semantic validation test suite
-3. Gather WordPress theme compatibility data
-
-### Medium Term
-1. API caching implementation
-2. Custom rule support
-3. Advanced analytics dashboard
-
----
-
-## Changelog
-
-### [2026-02-04] - Phase 2 Completion
-
-#### Added
-- UX Audit Integration with Gemini Vision API
-- UX audit runner (src/ai/ux-audit.js)
-- UX audit prompt definition (src/ai/prompts/ux_audit.py)
-- CLI flag: `--ux-audit` for clone-site command
-- Multi-viewport UX analysis (desktop, tablet, mobile)
-- Comprehensive UX report generation (analysis/ux-audit.md)
-- 20-test UX audit test suite (all passing)
-
-#### Modified
-- bin/commands/clone-site.js: Added --ux-audit flag integration
-- package.json: Added @google/generative-ai to optionalDependencies
-
-#### Quality
-- Code review score: 9/10
-- Test passing rate: 20/20 (100%)
-- Architecture compliance: Excellent
-- Security validation: Passed
-
-#### Specifications Met
-- ✅ 6-category UX analysis (visual hierarchy, navigation, typography, spacing, interactivity, responsive)
-- ✅ Severity levels (critical, major, minor)
-- ✅ Actionable recommendations
-- ✅ <10s report generation per 3 viewports
-- ✅ Graceful API key degradation
-
----
-
-### [2026-02-04] - Phase 1 Completion
-
-#### Added
-- Component verification system (header, footer, slider)
-- Visual diff generation with Playwright
-- Audit report generation in Markdown
-- Verification test suite (20+ tests)
-
-#### Quality
-- All success criteria met
-- Zero breaking changes
-- Comprehensive test coverage
-
----
-
-## Contact & Resources
-
-- **Architecture Docs:** `./docs/design-clone-architecture.md`
-- **CLI Reference:** `./docs/cli-reference.md`
-- **Implementation Plans:** `./plans/260204-1333-design-clone-improvements/`
-- **Code Review Reports:** `./plans/reports/`
-
----
-
-## Status Summary
-
-| Aspect | Status | Notes |
-|--------|--------|-------|
-| Phase 1 | ✅ COMPLETE | 100% complete, all tests passing |
-| Phase 2 | ✅ COMPLETE | 100% complete, 9/10 code review score |
-| Phase 3 | 🔄 PLANNED | Ready to start, architecture defined |
-| Testing | ✅ 82/82 passing | Full test suite operational |
-| Documentation | ✅ Updated | All phase deliverables documented |
-| Code Quality | ✅ High | Architecture-aligned, best practices followed |
-| Security | ✅ Compliant | API key handling, error management validated |
-

package/docs/troubleshooting.md

@@ -1,170 +0,0 @@
-# Troubleshooting
-
-Common issues and solutions.
-
-## Browser Issues
-
-### Chrome/Chromium not found
-
-**Error:** `Could not find Chrome`
-
-**Solution:**
-```bash
-# macOS
-brew install --cask google-chrome
-
-# Ubuntu
-sudo apt install chromium-browser
-
-# Or set path manually
-export CHROME_PATH="/path/to/chrome"
-```
-
-### Playwright launch fails
-
-**Error:** `Failed to launch browser`
-
-**Solutions:**
-1. Install Playwright: `npm install playwright` (includes bundled browsers)
-   - Or lighter: `npm install playwright-core` (requires Chrome installed)
-2. Verify Chrome is installed or use full `playwright` package
-3. Docker: Already includes `--no-sandbox` flag automatically
-
-## CSS Issues
-
-### CORS-blocked stylesheets
-
-**Symptom:** CSS extraction returns empty or partial styles.
-
-**Solution:** Some sites block cross-origin stylesheet access. Use browser DevTools manually or try `--wait 3000` for dynamic CSS.
-
-### CSS too large
-
-**Error:** `CSS file exceeds 10MB limit`
-
-**Solution:** filter-css.js has 10MB limit. Split manually or increase `MAX_CSS_INPUT_SIZE` in filter-css.js.
-
-## Python Issues
-
-### Module not found
-
-**Error:** `ModuleNotFoundError: google.genai`
-
-**Solution:**
-```bash
-pip install -r requirements.txt
-# Or: pip install google-genai
-```
-
-### Wrong Python version
-
-**Error:** `SyntaxError` on type hints
-
-**Solution:** Requires Python 3.9+. Check: `python3 --version`
-
-## Gemini API Issues
-
-### API key not set
-
-**Error:** `GEMINI_API_KEY not found`
-
-**Solution:** Create `.env` file:
-```bash
-GEMINI_API_KEY=your-api-key-here
-```
-
-### Rate limit exceeded
-
-**Error:** `429 Too Many Requests`
-
-**Solution:** Wait 1 minute, or use `--model gemini-1.5-flash` for lower limits.
-
-## Screenshot Issues
-
-### Incomplete page capture
-
-**Symptom:** Missing sections in screenshot.
-
-**Solutions:**
-1. Increase wait: `--wait 5000`
-2. Use full page: `--full-page`
-3. Check for lazy-loaded content
-
-### Wrong viewport size
-
-**Solution:** Specify custom viewports:
-```bash
---viewports '[{"width":1440,"height":900,"name":"custom"}]'
-```
-
-## clone-site Issues
-
-### No pages discovered
-
-**Symptom:** Only homepage cloned, other pages not found.
-
-**Causes:**
-- Site uses JS-rendered navigation (React/Vue/Angular)
-- Navigation not in standard selectors (header nav, footer nav)
-
-**Solutions:**
-```bash
-# Specify pages manually
-design-clone clone-site https://example.com --pages /,/about,/contact,/services
-
-# Increase max pages if hitting limit
-design-clone clone-site https://example.com --max-pages 20
-```
-
-### Links not working in cloned pages
-
-**Symptom:** Internal links point to original URLs.
-
-**Causes:**
-- Page not in discovered list
-- HTML file not found for rewriting
-
-**Solutions:**
-1. Check `manifest.json` for page list
-2. Ensure all pages captured successfully (check `capture-results.json`)
-3. Re-run with manual `--pages` flag including missing pages
-
-### CSS broken on some pages
-
-**Symptom:** Styling differs between cloned pages.
-
-**Causes:**
-- Page-specific CSS not merged
-- CSS extraction failed for some pages
-
-**Solutions:**
-1. Check `css/` folder for per-page CSS files
-2. Review merge stats in output
-3. Try with fewer pages to isolate issue
-
-### Timeout during capture
-
-**Error:** `Navigation timeout`
-
-**Causes:**
-- Large pages
-- Slow server
-- Too many pages
-
-**Solutions:**
-```bash
-# Reduce pages
-design-clone clone-site https://example.com --max-pages 5
-
-# Use specific viewports only
-design-clone clone-site https://example.com --viewports desktop
-```
-
-### Memory issues
-
-**Symptom:** Process crashes or hangs.
-
-**Solutions:**
-1. Reduce `--max-pages` to 5 or fewer
-2. Clone in batches
-3. Close other applications

package/requirements.txt

@@ -1,5 +0,0 @@
-# Design Clone Skill - Python Dependencies
-# Install: pip install -r requirements.txt
-
-# Gemini AI for structure analysis and token extraction
-google-genai>=1.0.0