perfectclone 0.1.0__tar.gz

perfectclone-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Eshaan Gulati
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

perfectclone-0.1.0/PKG-INFO

@@ -0,0 +1,192 @@
+Metadata-Version: 2.4
+Name: perfectclone
+Version: 0.1.0
+Summary: Clone any website 1:1 with a real browser, then edit it safely.
+Author: Eshaan Gulati
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/eshaangulati123/perfectclone-website-cloner
+Project-URL: Issues, https://github.com/eshaangulati123/perfectclone-website-cloner/issues
+Project-URL: Changelog, https://github.com/eshaangulati123/perfectclone-website-cloner/blob/main/CHANGELOG.md
+Keywords: website cloner,clone website,website copier,website mirror,playwright,nextjs,httrack alternative,web scraping
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Internet :: WWW/HTTP :: Site Management
+Classifier: Topic :: Software Development :: Build Tools
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: playwright>=1.40
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: pillow; extra == "dev"
+Requires-Dist: ruff; extra == "dev"
+Dynamic: license-file
+
+# perfectclone: website cloner that copies the real site, 1:1
+
+**Pull the real frontend of any public site in ~15 seconds. No AI, no tokens.**
+
+![Clone any website. Get the real files. huly.io cloned with perfectclone: 0.00% pixel difference, 14 seconds, 157 files, 0 LLM calls.](https://raw.githubusercontent.com/eshaangulati123/perfectclone-website-cloner/main/docs/images/huly-live-vs-clone.jpg)
+
+perfectclone clones any website 1:1. It crawls the site with a real browser (Playwright),
+downloads the site's own HTML, JavaScript, CSS, fonts and images, and gives you a folder you can
+serve, edit and deploy. Then it lets you rebrand it, rehost it and strip the original owner's
+trackers without breaking it, including Next.js sites that hydrate on load.
+
+```bash
+pip install perfectclone
+
+perfectclone clone example.com
+perfectclone serve example.com             # → http://localhost:8000
+```
+
+That's it. Chromium is downloaded automatically the first time you clone. Requires Python 3.10+.
+
+Or try it without installing anything, using [uv](https://docs.astral.sh/uv/):
+
+```bash
+uvx perfectclone clone example.com
+```
+
+## Why not an AI cloner?
+
+Most "clone any website" tools today regenerate the site: an AI agent looks at screenshots or
+scraped markup, writes a new React/Next.js app, and compares the result against the original
+with a visual-similarity score until it's close enough. That gets you a lookalike. The code is
+new, the behaviour is approximate, and there are always gaps.
+
+perfectclone doesn't regenerate anything. It mirrors the bytes the site actually serves, so
+the clone *is* the site: same markup, same bundles, same animations, same JavaScript running.
+Sometimes the real solution is the simple one.
+
+|                                         | AI cloners | wget / HTTrack | perfectclone |
+| --------------------------------------- | :--------: | :------------: | :----------: |
+| Copies the site's real files            | ❌         | ✅             | ✅           |
+| Pixel-identical on modern JS sites      | ❌         | ❌             | ✅           |
+| Catches lazy-loaded JS, fonts, images   | —          | ❌             | ✅           |
+| React / Next.js sites still run         | —          | ❌             | ✅           |
+| Rebrand without breaking the site       | ✅         | ⚠️             | ✅           |
+| Strips the original site's trackers     | —          | ❌             | ✅           |
+| Works without an LLM or API key         | ❌         | ✅             | ✅           |
+
+## Tested on real sites
+
+Each card is one site split down the middle: the live site on the left, the clone on the right.
+
+![Live vs clone split view for nextjs.org, astro.build, svelte.dev, vitepress.dev, docusaurus.io and wordpress.org](https://raw.githubusercontent.com/eshaangulati123/perfectclone-website-cloner/main/docs/images/compatibility.jpg)
+
+`scripts/compat.py` clones each site, serves the copy, and compares its home page with the live
+one at 1440×900, with animations and videos paused on the same frame:
+
+| Site | Built with | Pixel match | Hydration errors | Notes |
+| --- | --- | --- | --- | --- |
+| huly.io | Next.js | 100% | 0 | |
+| nextjs.org | Next.js | 100% | 0 | |
+| astro.build | Astro | 100% | 0 | |
+| svelte.dev | SvelteKit | 100% | 0 | |
+| vitepress.dev | VitePress (Vue) | 100% | 0 | |
+| docusaurus.io | Docusaurus (React) | 100% | 0 | |
+| wordpress.org/news | WordPress | 100% | 0 | |
+| paulgraham.com | Hand-written HTML | 100% | 0 | |
+| example.com | Static HTML | 100% | 0 | |
+| framer.com | Framer | 96% | 0 | Cookie banner needs Framer's backend |
+| webflow.com | Webflow | 93% | 0 | Cookie banner won't run on localhost; carousel caught mid-scroll |
+
+Every clone loaded with zero requests to trackers. Run it yourself with
+`python scripts/compat.py`, and please open an issue for any site that doesn't come out right.
+
+## Commands
+
+```bash
+perfectclone clone <url> [-o out] [--max-pages 200] [--extract] [--keep-trackers] [--ignore-robots]
+perfectclone serve <site> [-p 8000]
+perfectclone replace <site> <old> <new> [--exact-case] [--substring]
+perfectclone rehost <site> <old-origin> <new-origin>
+perfectclone strip-trackers <site>
+```
+
+- **clone** writes `out/site/` (the working copy) and `out/manifest.json` (pages, failures,
+  third-party hosts the site uses). `--extract` also saves each page's text, metadata
+  (headings, links, images, forms, JSON-LD) and a full-page screenshot to `out/extract/`.
+  Trackers are stripped by default.
+- **replace** renames text everywhere: HTML, JS, CSS, JSON, SVG. It also handles the UPPER,
+  lower and Capitalized variants, and leaves URLs and asset paths alone so nothing 404s.
+- **rehost** points canonical, Open Graph, JSON-LD and sitemap URLs at your domain.
+- **serve** works like a static host: clean URLs (`/about` → `/about/index.html`), and
+  `/_next/image` requests are served from the mirrored originals.
+
+Rebrand a clone and put it online:
+
+```bash
+perfectclone clone acme.com -o acme
+perfectclone replace acme "Acme" "Globex"
+perfectclone rehost  acme https://acme.com https://globex.com
+npx netlify-cli deploy --dir acme/site --prod      # or any static host
+```
+
+## How it works
+
+1. **Crawl with a real browser.** Each page is rendered in Chromium and scrolled to the bottom,
+   and every response is recorded. That catches what static mirrors miss: code-split JS chunks,
+   fonts requested from CSS, images behind lazy loading. Links are followed breadth-first,
+   seeded from the sitemap. robots.txt is respected unless you pass `--ignore-robots`.
+2. **Mirror the server's bytes.** Pages are saved as the HTML the *server* sends, not the
+   rendered DOM, because that's what the site's JavaScript expects to hydrate. Assets keep
+   their URL paths, and CSS/JS are scanned for further references (`url()`, `srcset`, chunk
+   paths) until nothing new turns up.
+3. **Edit without breaking hydration.** A Next.js App Router page ships its HTML *and* a
+   serialized copy of the React tree in `self.__next_f.push(...)` script chunks. Change one and
+   not the other, and React throws a hydration error and re-renders from the payload, undoing
+   your edit. perfectclone decodes the payload stream, edits it row by row, recomputes the
+   UTF-8 byte lengths of length-prefixed text rows (`<id>:T<hex>,…`), rejoins rows that span
+   chunks, and writes it back next to the matching HTML edit.
+4. **Strip trackers.** Google Analytics/Tag Manager, the Meta pixel, LinkedIn Insight, Hotjar,
+   Clarity, Segment, PostHog, HubSpot, TikTok, Reddit, X, Cloudflare Web Analytics, RB2B and
+   more. They're removed from `<script>`/`<noscript>` tags, from preload hints, and from Next.js
+   `next/script` elements that only exist in the payload.
+
+## Limits
+
+- **No backend.** Forms, logins, search and API calls still go to the original servers (or
+  fail). perfectclone copies the front end.
+- **Next.js client-side navigation** needs each page's RSC payload answered for `?_rsc=`
+  requests. perfectclone mirrors them and `perfectclone serve` routes them. On a plain static
+  host, internal links fall back to full page loads: everything still works, just without the
+  instant transitions.
+- **Chunks that are only requested after a click** (say, a modal's code) are captured if the
+  crawl triggered them or a bundle names them as a string. A bundle can also assemble a chunk
+  URL at runtime, and that one may be missed.
+- **Bot protection** (CAPTCHAs, aggressive Cloudflare rules) can block the crawl. perfectclone
+  does not try to get around it.
+- Embeds (YouTube, Cal.com, maps) and third-party CDNs keep loading from their own hosts.
+
+## Roadmap
+
+**Clone apps behind a login, like dashboards.** Today perfectclone sees what an anonymous visitor
+sees, and data that loads from APIs after the page renders isn't kept. The plan, for apps you
+have an account on:
+
+- **Crawl as you.** Sign in once in a browser window; perfectclone saves the session and
+  crawls with it.
+- **Record API responses.** Keep every JSON response the app fetches during the crawl and have
+  `perfectclone serve` replay them, so charts, tables and lists show real data offline.
+- **Explore by clicking.** Click through navigation, tabs and menus to reach views that only
+  exist in client-side routing.
+
+The result is a clickable snapshot of the UI and its data at capture time. Saving, server-side
+filtering and live updates still need the real backend.
+
+Other ideas: hydration-aware editing for Nuxt, SvelteKit and Remix payloads, and a deploy
+helper that writes `_redirects` / `vercel.json` rules so `?_rsc=` and `/_next/image` work on
+static hosts. Contributions welcome.
+
+## Contributing
+
+perfectclone is open source under the [MIT License](https://github.com/eshaangulati123/perfectclone-website-cloner/blob/main/LICENSE). Issues and pull requests are
+welcome, especially reports of sites that don't clone cleanly. See
+[CONTRIBUTING.md](https://github.com/eshaangulati123/perfectclone-website-cloner/blob/main/CONTRIBUTING.md), and please follow the [Code of Conduct](https://github.com/eshaangulati123/perfectclone-website-cloner/blob/main/CODE_OF_CONDUCT.md).
+Report security issues privately as described in [SECURITY.md](https://github.com/eshaangulati123/perfectclone-website-cloner/blob/main/SECURITY.md).

perfectclone-0.1.0/README.md

@@ -0,0 +1,164 @@
+# perfectclone: website cloner that copies the real site, 1:1
+
+**Pull the real frontend of any public site in ~15 seconds. No AI, no tokens.**
+
+![Clone any website. Get the real files. huly.io cloned with perfectclone: 0.00% pixel difference, 14 seconds, 157 files, 0 LLM calls.](https://raw.githubusercontent.com/eshaangulati123/perfectclone-website-cloner/main/docs/images/huly-live-vs-clone.jpg)
+
+perfectclone clones any website 1:1. It crawls the site with a real browser (Playwright),
+downloads the site's own HTML, JavaScript, CSS, fonts and images, and gives you a folder you can
+serve, edit and deploy. Then it lets you rebrand it, rehost it and strip the original owner's
+trackers without breaking it, including Next.js sites that hydrate on load.
+
+```bash
+pip install perfectclone
+
+perfectclone clone example.com
+perfectclone serve example.com             # → http://localhost:8000
+```
+
+That's it. Chromium is downloaded automatically the first time you clone. Requires Python 3.10+.
+
+Or try it without installing anything, using [uv](https://docs.astral.sh/uv/):
+
+```bash
+uvx perfectclone clone example.com
+```
+
+## Why not an AI cloner?
+
+Most "clone any website" tools today regenerate the site: an AI agent looks at screenshots or
+scraped markup, writes a new React/Next.js app, and compares the result against the original
+with a visual-similarity score until it's close enough. That gets you a lookalike. The code is
+new, the behaviour is approximate, and there are always gaps.
+
+perfectclone doesn't regenerate anything. It mirrors the bytes the site actually serves, so
+the clone *is* the site: same markup, same bundles, same animations, same JavaScript running.
+Sometimes the real solution is the simple one.
+
+|                                         | AI cloners | wget / HTTrack | perfectclone |
+| --------------------------------------- | :--------: | :------------: | :----------: |
+| Copies the site's real files            | ❌         | ✅             | ✅           |
+| Pixel-identical on modern JS sites      | ❌         | ❌             | ✅           |
+| Catches lazy-loaded JS, fonts, images   | —          | ❌             | ✅           |
+| React / Next.js sites still run         | —          | ❌             | ✅           |
+| Rebrand without breaking the site       | ✅         | ⚠️             | ✅           |
+| Strips the original site's trackers     | —          | ❌             | ✅           |
+| Works without an LLM or API key         | ❌         | ✅             | ✅           |
+
+## Tested on real sites
+
+Each card is one site split down the middle: the live site on the left, the clone on the right.
+
+![Live vs clone split view for nextjs.org, astro.build, svelte.dev, vitepress.dev, docusaurus.io and wordpress.org](https://raw.githubusercontent.com/eshaangulati123/perfectclone-website-cloner/main/docs/images/compatibility.jpg)
+
+`scripts/compat.py` clones each site, serves the copy, and compares its home page with the live
+one at 1440×900, with animations and videos paused on the same frame:
+
+| Site | Built with | Pixel match | Hydration errors | Notes |
+| --- | --- | --- | --- | --- |
+| huly.io | Next.js | 100% | 0 | |
+| nextjs.org | Next.js | 100% | 0 | |
+| astro.build | Astro | 100% | 0 | |
+| svelte.dev | SvelteKit | 100% | 0 | |
+| vitepress.dev | VitePress (Vue) | 100% | 0 | |
+| docusaurus.io | Docusaurus (React) | 100% | 0 | |
+| wordpress.org/news | WordPress | 100% | 0 | |
+| paulgraham.com | Hand-written HTML | 100% | 0 | |
+| example.com | Static HTML | 100% | 0 | |
+| framer.com | Framer | 96% | 0 | Cookie banner needs Framer's backend |
+| webflow.com | Webflow | 93% | 0 | Cookie banner won't run on localhost; carousel caught mid-scroll |
+
+Every clone loaded with zero requests to trackers. Run it yourself with
+`python scripts/compat.py`, and please open an issue for any site that doesn't come out right.
+
+## Commands
+
+```bash
+perfectclone clone <url> [-o out] [--max-pages 200] [--extract] [--keep-trackers] [--ignore-robots]
+perfectclone serve <site> [-p 8000]
+perfectclone replace <site> <old> <new> [--exact-case] [--substring]
+perfectclone rehost <site> <old-origin> <new-origin>
+perfectclone strip-trackers <site>
+```
+
+- **clone** writes `out/site/` (the working copy) and `out/manifest.json` (pages, failures,
+  third-party hosts the site uses). `--extract` also saves each page's text, metadata
+  (headings, links, images, forms, JSON-LD) and a full-page screenshot to `out/extract/`.
+  Trackers are stripped by default.
+- **replace** renames text everywhere: HTML, JS, CSS, JSON, SVG. It also handles the UPPER,
+  lower and Capitalized variants, and leaves URLs and asset paths alone so nothing 404s.
+- **rehost** points canonical, Open Graph, JSON-LD and sitemap URLs at your domain.
+- **serve** works like a static host: clean URLs (`/about` → `/about/index.html`), and
+  `/_next/image` requests are served from the mirrored originals.
+
+Rebrand a clone and put it online:
+
+```bash
+perfectclone clone acme.com -o acme
+perfectclone replace acme "Acme" "Globex"
+perfectclone rehost  acme https://acme.com https://globex.com
+npx netlify-cli deploy --dir acme/site --prod      # or any static host
+```
+
+## How it works
+
+1. **Crawl with a real browser.** Each page is rendered in Chromium and scrolled to the bottom,
+   and every response is recorded. That catches what static mirrors miss: code-split JS chunks,
+   fonts requested from CSS, images behind lazy loading. Links are followed breadth-first,
+   seeded from the sitemap. robots.txt is respected unless you pass `--ignore-robots`.
+2. **Mirror the server's bytes.** Pages are saved as the HTML the *server* sends, not the
+   rendered DOM, because that's what the site's JavaScript expects to hydrate. Assets keep
+   their URL paths, and CSS/JS are scanned for further references (`url()`, `srcset`, chunk
+   paths) until nothing new turns up.
+3. **Edit without breaking hydration.** A Next.js App Router page ships its HTML *and* a
+   serialized copy of the React tree in `self.__next_f.push(...)` script chunks. Change one and
+   not the other, and React throws a hydration error and re-renders from the payload, undoing
+   your edit. perfectclone decodes the payload stream, edits it row by row, recomputes the
+   UTF-8 byte lengths of length-prefixed text rows (`<id>:T<hex>,…`), rejoins rows that span
+   chunks, and writes it back next to the matching HTML edit.
+4. **Strip trackers.** Google Analytics/Tag Manager, the Meta pixel, LinkedIn Insight, Hotjar,
+   Clarity, Segment, PostHog, HubSpot, TikTok, Reddit, X, Cloudflare Web Analytics, RB2B and
+   more. They're removed from `<script>`/`<noscript>` tags, from preload hints, and from Next.js
+   `next/script` elements that only exist in the payload.
+
+## Limits
+
+- **No backend.** Forms, logins, search and API calls still go to the original servers (or
+  fail). perfectclone copies the front end.
+- **Next.js client-side navigation** needs each page's RSC payload answered for `?_rsc=`
+  requests. perfectclone mirrors them and `perfectclone serve` routes them. On a plain static
+  host, internal links fall back to full page loads: everything still works, just without the
+  instant transitions.
+- **Chunks that are only requested after a click** (say, a modal's code) are captured if the
+  crawl triggered them or a bundle names them as a string. A bundle can also assemble a chunk
+  URL at runtime, and that one may be missed.
+- **Bot protection** (CAPTCHAs, aggressive Cloudflare rules) can block the crawl. perfectclone
+  does not try to get around it.
+- Embeds (YouTube, Cal.com, maps) and third-party CDNs keep loading from their own hosts.
+
+## Roadmap
+
+**Clone apps behind a login, like dashboards.** Today perfectclone sees what an anonymous visitor
+sees, and data that loads from APIs after the page renders isn't kept. The plan, for apps you
+have an account on:
+
+- **Crawl as you.** Sign in once in a browser window; perfectclone saves the session and
+  crawls with it.
+- **Record API responses.** Keep every JSON response the app fetches during the crawl and have
+  `perfectclone serve` replay them, so charts, tables and lists show real data offline.
+- **Explore by clicking.** Click through navigation, tabs and menus to reach views that only
+  exist in client-side routing.
+
+The result is a clickable snapshot of the UI and its data at capture time. Saving, server-side
+filtering and live updates still need the real backend.
+
+Other ideas: hydration-aware editing for Nuxt, SvelteKit and Remix payloads, and a deploy
+helper that writes `_redirects` / `vercel.json` rules so `?_rsc=` and `/_next/image` work on
+static hosts. Contributions welcome.
+
+## Contributing
+
+perfectclone is open source under the [MIT License](https://github.com/eshaangulati123/perfectclone-website-cloner/blob/main/LICENSE). Issues and pull requests are
+welcome, especially reports of sites that don't clone cleanly. See
+[CONTRIBUTING.md](https://github.com/eshaangulati123/perfectclone-website-cloner/blob/main/CONTRIBUTING.md), and please follow the [Code of Conduct](https://github.com/eshaangulati123/perfectclone-website-cloner/blob/main/CODE_OF_CONDUCT.md).
+Report security issues privately as described in [SECURITY.md](https://github.com/eshaangulati123/perfectclone-website-cloner/blob/main/SECURITY.md).

perfectclone-0.1.0/pyproject.toml

@@ -0,0 +1,52 @@
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "perfectclone"
+dynamic = ["version"]
+description = "Clone any website 1:1 with a real browser, then edit it safely."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Eshaan Gulati" }]
+requires-python = ">=3.10"
+dependencies = ["playwright>=1.40"]
+keywords = ["website cloner", "clone website", "website copier", "website mirror", "playwright", "nextjs", "httrack alternative", "web scraping"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Topic :: Internet :: WWW/HTTP :: Site Management",
+    "Topic :: Software Development :: Build Tools",
+]
+
+[project.urls]
+Homepage = "https://github.com/eshaangulati123/perfectclone-website-cloner"
+Issues = "https://github.com/eshaangulati123/perfectclone-website-cloner/issues"
+Changelog = "https://github.com/eshaangulati123/perfectclone-website-cloner/blob/main/CHANGELOG.md"
+
+[project.optional-dependencies]
+dev = ["pytest", "pillow", "ruff"]
+
+[project.scripts]
+perfectclone = "perfectclone.cli:main"
+
+[tool.setuptools.dynamic]
+version = { attr = "perfectclone.__version__" }
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.ruff]
+line-length = 130
+target-version = "py310"
+
+[tool.ruff.lint]
+select = ["E", "F", "W", "I", "B", "UP"]

perfectclone-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

perfectclone-0.1.0/src/perfectclone/__init__.py

@@ -0,0 +1,2 @@
+"""Clone any website 1:1 with a real browser, then edit it safely."""
+__version__ = "0.1.0"

perfectclone-0.1.0/src/perfectclone/__main__.py

@@ -0,0 +1,3 @@
+from .cli import main
+
+main()

perfectclone-0.1.0/src/perfectclone/cli.py

@@ -0,0 +1,112 @@
+"""perfectclone command line."""
+import argparse
+import json
+import sys
+from pathlib import Path
+from urllib.parse import urlparse
+
+from . import __version__
+from .edit import localize, rehost, replace
+from .serve import serve
+from .trackers import strip
+from .util import site_dir
+
+
+def cmd_clone(a):
+    # Imported here so the editing commands don't pay for loading Playwright.
+    from .crawl import crawl
+    from .mirror import mirror
+
+    out = Path(a.out)
+    site = out / "site"
+    print(f"Crawling {a.url}")
+    pages, assets, external, skipped = crawl(
+        a.url, max_pages=a.max_pages, respect_robots=not a.ignore_robots,
+        extract_dir=out / "extract" if a.extract else None,
+    )
+    if not pages:
+        sys.exit("No pages could be loaded." + (f" First problem: {skipped[0]}" if skipped else ""))
+    print(f"Mirroring into {site}")
+    saved, fetched, failures = mirror(pages, assets, site)
+    localize(site, a.url)
+    if a.strip_trackers:
+        print("Removing trackers")
+        strip(site)
+    manifest = {
+        "source": a.url, "pages": pages, "assets_fetched": fetched, "failures": failures,
+        "skipped": skipped, "external_hosts": external,
+    }
+    (out / "manifest.json").write_text(json.dumps(manifest, indent=2))
+    print(f"\nDone: {saved} pages, {fetched} assets → {site}")
+    if failures:
+        print(f"  {len(failures)} URLs failed to download (see {out / 'manifest.json'})")
+    if external:
+        print(f"  The original also used these hosts (embeds, CDNs, analytics): {', '.join(external)}")
+    print(f"\nPreview it:  perfectclone serve {out}")
+
+
+def cmd_serve(a):
+    serve(a.site, a.port)
+
+
+def cmd_replace(a):
+    replace(site_dir(a.site), a.old, a.new, variants=not a.exact_case, whole_word=not a.substring)
+
+
+def cmd_rehost(a):
+    rehost(site_dir(a.site), a.old_origin, a.new_origin)
+
+
+def cmd_strip(a):
+    strip(site_dir(a.site))
+
+
+def main(argv=None):
+    p = argparse.ArgumentParser(
+        prog="perfectclone", description="Clone any website 1:1 with a real browser, then edit it safely.")
+    p.add_argument("--version", action="version", version=__version__)
+    sub = p.add_subparsers(dest="cmd", required=True)
+
+    c = sub.add_parser("clone", help="crawl a site and save a working local copy")
+    c.add_argument("url")
+    c.add_argument("-o", "--out", default=None, help="output folder (default: the site's hostname)")
+    c.add_argument("--max-pages", type=int, default=200)
+    c.add_argument("--extract", action="store_true", help="also save each page's text, metadata and a full-page screenshot")
+    c.add_argument("--keep-trackers", dest="strip_trackers", action="store_false", help="keep the original analytics/ad pixels")
+    c.add_argument("--ignore-robots", action="store_true", help="crawl pages robots.txt disallows")
+    c.set_defaults(fn=cmd_clone)
+
+    s = sub.add_parser("serve", help="serve a clone locally")
+    s.add_argument("site")
+    s.add_argument("-p", "--port", type=int, default=8000)
+    s.set_defaults(fn=cmd_serve)
+
+    r = sub.add_parser("replace", help="replace text across the clone (skips URLs, Next.js-safe)")
+    r.add_argument("site")
+    r.add_argument("old")
+    r.add_argument("new")
+    r.add_argument("--exact-case", action="store_true", help="don't also replace UPPER/lower/Capitalized variants")
+    r.add_argument("--substring", action="store_true", help="match inside words too")
+    r.set_defaults(fn=cmd_replace)
+
+    h = sub.add_parser("rehost", help="point canonical/og/sitemap URLs at a new origin")
+    h.add_argument("site")
+    h.add_argument("old_origin")
+    h.add_argument("new_origin")
+    h.set_defaults(fn=cmd_rehost)
+
+    t = sub.add_parser("strip-trackers", help="remove analytics and ad pixels")
+    t.add_argument("site")
+    t.set_defaults(fn=cmd_strip)
+
+    a = p.parse_args(argv)
+    if a.cmd == "clone":
+        if "://" not in a.url:
+            a.url = "https://" + a.url
+        if not a.out:
+            a.out = urlparse(a.url).netloc.removeprefix("www.") or "clone"
+    a.fn(a)
+
+
+if __name__ == "__main__":
+    main()