From 13d15e201495639f73aa905076db923557fcc111 Mon Sep 17 00:00:00 2001 From: Christian Date: Mon, 8 Jun 2026 20:19:37 -0400 Subject: [PATCH] Update README.md --- README.md | 87 +++++++++++++++++++------------------------------------ 1 file changed, 29 insertions(+), 58 deletions(-) diff --git a/README.md b/README.md index 3f65322..36543d0 100644 --- a/README.md +++ b/README.md @@ -1,10 +1,8 @@ -
+content = """
# ⇅ Portage -**A universal browser data swap.** Export your browsing data to one portable JSON bundle, then import it into *any* browser — Chrome → Firefox, Firefox → Chrome, or the **same browser** on a new machine or profile. - -Two extensions, one job. Monochrome, professional UI with animated cards, live progress bars and honest reporting. Everything runs locally — nothing is ever uploaded. +**A universal browser data swap.** Export your setup to a portable JSON bundle. Import it anywhere. Chrome to Firefox, Firefox to Chrome, or a fresh install of the same browser. No cloud, no lock-in. [github.com/pvrzz/Portage](https://github.com/pvrzz/Portage/) @@ -14,77 +12,50 @@ Two extensions, one job. Monochrome, professional UI with animated cards, live p ## Why -Browsers make it hard to take your data with you. Portage is a tiny, transparent tool that scans everything a browser extension is *allowed* to read, packs it into a human-readable `*.portage.json` file you control, and recreates it on the other side. Because the bundle is just JSON, it doesn't care which browser made it — it's a universal swap: - -- **Chrome → Firefox** and **Firefox → Chrome** -- **Chrome → Chrome** / **Firefox → Firefox** (new computer, new profile, reinstall, backup & restore) +Browsers intentionally make it annoying to leave their ecosystem. Portage is a straightforward, open-source tool that reads what it's allowed to read, dumps it into a human-readable `*.portage.json` file, and rebuilds it on the other side. Because the export is just plain JSON, it bridges the gap between competing browsers or lets you easily migrate to a new machine. ## What transfers -Extensions can only use the WebExtension APIs — they can't read profile files off disk. Everything below round-trips through those APIs. Nothing is collected that can't be acted on. +Extensions are locked out of reading local profile files straight from your hard drive, so Portage routes everything through official WebExtension APIs. | Data | Export | Import | |---|---|---| -| **Bookmarks** | ✅ full tree | ✅ recreated in a `Portage Import` folder | -| **History** | ✅ url / title / time / visits | ✅ re-added (Firefox keeps titles + times; Chrome's API takes URL only) | -| **Cookies** | ✅ all (needs host permission) | ✅ re-set so logins carry over | -| **Open tabs** | ✅ | ✅ reopened | -| **Recently closed** | ✅ | ✅ reopened as tabs | -| **Reading list** | ✅ (Chrome only — Firefox has no API) | ✅ Chrome → reading list · Firefox → bookmark folder | -| **Extensions** | ✅ list → **`.txt` checklist** | ℹ️ can't auto-install — see below | +| **Bookmarks** | ✅ Full tree | ✅ Recreated in a `Portage Import` folder | +| **History** | ✅ URLs, titles, timestamps | ✅ Re-added (Firefox keeps full metadata; Chrome limits to URLs) | +| **Cookies** | ✅ Full export | ✅ Re-injected to keep you logged in | +| **Open tabs** | ✅ Active & recently closed | ✅ Reopened instantly | +| **Reading list** | ✅ Exported (Chrome only) | ✅ Chrome: Reading list · Firefox: Bookmarks folder | +| **Extensions** | ✅ Exported as a text checklist | ℹ️ Cannot auto-install (see below) | -### Extensions → a reinstall checklist (`.txt`) -**No browser exposes an API to install another extension** (`management.install` does not exist), so Portage can't reinstall them for you. Instead, exporting writes a second file — `portage--extensions-.txt` — listing every extension with its description and **add-on store search links for both Firefox and Chrome**. Paste it into an AI assistant ("find these as Firefox add-ons") or click through the links. The import screen shows the same list with clickable links and a re-download button. +### The Extension Workaround (`.txt`) +There is no API for an extension to silently install another extension. To handle this, Portage generates a secondary `portage--extensions-.txt` file. This acts as a manual checklist, complete with direct links to the Chrome Web Store or Firefox Add-ons site. Click through the links to rebuild your lineup, or drop the list into an AI to track down the equivalents for your new browser. -### Not included -Passwords and autofill have no extension API at all, so Portage leaves them out entirely. Export them from your browser's built-in settings (Chrome: Password Manager → Export; Firefox: Passwords → Import from a file). +### What's Missing +Passwords and autofill data are completely walled off from extension APIs. You will need to export those manually from your browser's built-in settings (Chrome: Password Manager → Export; Firefox: Passwords → Import). -## Privacy +## Privacy & Security Model -- Portage holds your data **only in the page's memory**, and **wipes it the moment you export, copy, or finish importing**. It never writes to extension storage and makes no network requests. -- The bundle is **plain-text JSON and includes your cookies** (session tokens). Treat it like a password file: keep it local and delete it once imported. -- Importing the same bundle twice is not deduplicated — it creates another `Portage Import` folder and re-adds history/cookies. Import once and verify. +* **Zero telemetry:** Everything runs entirely on your local machine. No network requests are ever made. +* **Memory only:** Portage holds your data in the active page's memory and wipes it completely as soon as you export, import, or close the tab. +* **Handle with care:** Your export bundle contains live session cookies. Treat this file exactly like an exported password vault. Keep it local, import it, and delete it immediately. +* **No deduplication:** Importing the exact same file twice will duplicate your history and cookies. Just run it once and verify. -## Install (unpacked / temporary) +## Install (Unpacked) ### Chrome -1. `chrome://extensions` → enable **Developer mode**. -2. **Load unpacked** → select the `chrome/` folder. -3. Click the Portage toolbar icon → **Open Portage**. +1. Navigate to `chrome://extensions` and toggle on **Developer mode**. +2. Click **Load unpacked** and select the `chrome/` directory. +3. Click the Portage icon in your extension toolbar to launch. ### Firefox -1. `about:debugging#/runtime/this-firefox`. -2. **Load Temporary Add-on…** → pick any file in `firefox/` (e.g. `manifest.json`). - - Temporary add-ons are removed on restart — reload each session, or sign/package for a permanent install. -3. Click the Portage toolbar icon → **Open Portage**. +1. Navigate to `about:debugging#/runtime/this-firefox`. +2. Click **Load Temporary Add-on…** and select the `manifest.json` inside the `firefox/` directory. +3. Temporary add-ons wipe when Firefox restarts. You'll need to reload it for your next session, or sign the package for a permanent install. +4. Click the Portage icon in your extension toolbar to launch. ## Usage -1. **Source browser:** open Portage → **Export** → **Scan** → toggle off anything you don't want → **Export bundle** (saves the `.json` and, if selected, the extensions `.txt`). The data is wiped from memory right after. -2. **Target browser:** open Portage → **Import** → drop in the `.portage.json` → review → **Import selected**. Live per-category progress and an imported/skipped tally are shown. +1. **Export:** Open Portage on your old browser, click **Scan**, uncheck anything you want to leave behind, and hit **Export bundle**. It drops the JSON (and the optional extension checklist) right to your downloads. +2. **Import:** Open Portage on your new browser, drag and drop the `.portage.json` file, review the stats, and hit **Import selected**. ## Layout - -``` -portage/ -├─ chrome/ # MV3 extension for Chrome -├─ firefox/ # MV3 (gecko) extension for Firefox -│ ├─ manifest.json # only the manifest + icons differ between the two -│ ├─ popup.{html,js} # toolbar launcher + quick counts -│ ├─ dashboard.{html,js} # unified Export + Import engine (auto-detects browser) -│ ├─ background.js -│ └─ styles.css # shared monochrome design system -└─ LICENSE # MIT -``` - -## License - -[MIT](LICENSE) © pvrz - ---- - -
- -developed by pvrz ♥ - -