chrome-tools 1.1.6 → 1.1.7

package/dist/bin/cli.js

@@ -1,2 +1,557 @@
 #!/usr/bin/env node
-import{readFileSync as o,existsSync as e}from"node:fs";import{join as r}from"node:path";import{Command as t}from"commander";import s from"chalk";import i from"cli-table3";import{discoverProfiles as n,getProfileMetadata as l,getProfileStates as a,getDirectorySize as c,detectInstalledBrowsers as d}from"../src/core/chrome.js";import{setActiveBrowser as m,getActiveBrowser as p,isKeychainAccessDenied as f}from"../src/core/platform/index.js";import{getPasswords as h}from"../src/modules/passwords.js";import{getBookmarks as u}from"../src/modules/bookmarks.js";import{getHistory as g,getSearchTerms as w}from"../src/modules/history.js";import{getCookies as b}from"../src/modules/cookies.js";import{getLocalStorage as y}from"../src/modules/local-storage.js";import{getAutofillEntries as S,getCreditCards as v,getAddresses as k}from"../src/modules/autofill.js";import{getDownloads as L}from"../src/modules/downloads.js";import{getExtensions as P}from"../src/modules/extensions.js";import{getSearchEngines as D}from"../src/modules/search-engines.js";import{getTopSites as j}from"../src/modules/top-sites.js";const N=function(){const t={...process.env},s=r(process.cwd(),".env");if(e(s))try{const e=o(s,"utf8");for(const o of e.split(/\r?\n/)){const e=o.trim();if(!e||e.startsWith("#"))continue;const r=e.indexOf("=");if(-1!==r){const o=e.substring(0,r).trim();let s=e.substring(r+1).trim();(s.startsWith('"')&&s.endsWith('"')||s.startsWith("'")&&s.endsWith("'"))&&(s=s.slice(1,-1)),t[o]=s}}}catch{}return t}(),B=N.PROFILE_PATH||void 0,C=N.PROFILE_NAME||void 0,$=N.BROWSER||N.CHROME_BROWSER||void 0;function O(o){console.log(JSON.stringify(o,null,2))}function R(o,e){return new i({head:o.map(o=>s.bold.white(o)),colWidths:e,wordWrap:!0,style:{border:["grey"],head:[]}})}function E(o,e){0===e?console.log(s.yellow(`\n⚠ No ${o} found.\n`)):console.log(s.green(`\n✔ Found ${e} ${o}.\n`))}let U=null;function x(o,e){return U?(U.push({browser:p().name,results:e}),!0):!!o.json&&(O(e),!0)}function F(o){const e=o.optsWithGlobals(),r=Boolean(e.browser)||Boolean(e.allBrowsers)||Boolean($);return e.browser=e.browser||$||void 0,e.profilePath||(e.profilePath=r?void 0:B),e.profile||(e.profile=r?void 0:C),e}function W(o,e){e.allBrowsers?function(o,e){const r=d();if(0===r.length)return e.json?O([]):void console.log(s.yellow("\n⚠ No supported Chromium browsers found on this machine.\n"));const t={...e,profilePath:void 0};if(e.json){U=[];try{for(const e of r){m(e.browser.id);try{o(t)}catch(o){U.push({browser:e.browser.name,results:{error:o?.message??String(o)}})}}O(U)}finally{U=null}}else for(const e of r){m(e.browser.id),console.log(s.bold.magenta(`\n══════════ ${e.browser.name} ══════════`));try{o(t)}catch(o){f(o)?(console.log(s.red(`  🔑 No keychain access — skipped (${o.service}).`)),console.log(s.dim(`  ${o.message.split("\n").join("\n  ")}`))):console.log(s.red(`  ⚠ Skipped: ${o?.message??String(o)}`))}}}(o,e):(m(e.browser),o(e))}function I(o){const e=d({includeMissing:!0});if(o.json)return O(e.map(o=>({id:o.browser.id,name:o.browser.name,installed:o.installed,profileCount:o.profileCount,path:o.chromeDir,safeStorageLabel:o.browser.safeStorageLabel})));const r=e.filter(o=>o.installed);console.log(s.bold(`\n🌐 Supported browsers (${r.length} installed):\n`));const t=R(["Browser","Id","Installed","Profiles","Path"],[20,14,11,9,50]);for(const o of e)t.push([s.white(o.browser.name),s.cyan(o.browser.id),o.installed?s.green("✓"):s.dim("✗"),o.installed?s.yellow(String(o.profileCount)):s.dim("—"),s.dim(o.chromeDir)]);console.log(t.toString())}function M(o){return o.option("--profile-path <path>","Custom browser User Data Path (overrides --browser)").option("--profile <name>","Target a specific profile").option("--browser <name>","Browser to read (chrome, edge, brave, comet, vivaldi, opera, chromium…)").option("--all-browsers","Read from every installed Chromium browser").option("--json","Output as JSON")}function T(o){return o.option("--search <term>","Filter results (case-insensitive)")}function A(o,e=100){return o.option("--limit <n>","Limit number of results",String(e))}const z=new t,V=JSON.parse(o(new URL("../../package.json",import.meta.url),"utf8"));z.name("chrome-tools").description(s.bold.cyan("Chrome Data Toolkit")+s.dim(" — Extract passwords, bookmarks, history, cookies, and more from Chrome on macOS, Windows, and Linux")).version(V.version).option("--passwords","Shortcut: list saved passwords").option("--bookmarks","Shortcut: list bookmarks").option("--local-storage","Shortcut: list localStorage entries").option("--profiles","Shortcut: list profiles").option("--browsers","Shortcut: list supported / installed browsers").option("--size","Show each profile's size on disk when listing profiles (slower)").option("--profile-path <path>","Custom browser User Data Path (overrides --browser)").option("--profile <name>","Target a specific profile").option("--browser <name>","Browser to read (chrome, edge, brave, comet, vivaldi, opera, chromium…)").option("--all-browsers","Read from every installed Chromium browser").option("--json","Output as JSON").option("--search <term>","Filter results (for shortcut flags)").option("--limit <n>","Limit results (for shortcut flags)").action((o,e)=>{const r=F(e);r.browsers?I(r):r.passwords?W(G,r):r.bookmarks?W(_,r):r.localStorage?W(Y,r):W(H,r)});const J=z.command("profiles").description("List Chrome profiles");M(J).option("--size","Compute and show each profile's size on disk (slower)").action((o,e)=>{W(H,F(e))});M(J.command("states").description("Show detailed profile states with available data files")).action((o,e)=>W(K,F(e)));function H(o){const e=n(o.profilePath),r=l(o.profilePath),t=Boolean(o.size);if(o.json){const s=new Map(r.map(o=>[o.directory,o]));return void x(o,e.map(o=>({...o,...s.get(o.name)||{},...t?{sizeBytes:c(o.path)}:{}})))}if(0===e.length)return void console.log(s.yellow("\n⚠ No Chrome profiles found.\n"));const i=new Map(r.map(o=>[o.directory,o]));console.log(s.bold(`\n📁 Discovered ${e.length} profile(s):\n`));const a=R(t?["Directory","Display Name","Email","Size","Path"]:["Directory","Display Name","Email","Path"],t?[16,22,30,10,42]:[16,22,30,50]);for(const o of e){const e=i.get(o.name)||{},r=[s.cyan(o.name),s.white(e.name||o.name),s.dim(e.email||"—")];t&&r.push(s.yellow(Z(c(o.path)))),r.push(s.dim(o.path)),a.push(r)}console.log(a.toString()),E("profile(s)",e.length)}function K(o){const e=a(o.profilePath);if(o.json)x(o,e);else if(0!==e.length){console.log(s.bold(`\n📊 Profile States (${e.length} profile(s)):\n`));for(const o of e){console.log(s.bold.cyan(`  ${o.displayName}`)+s.dim(` (${o.directory})`)),o.email&&console.log(s.dim(`    Email: ${o.email}`)),console.log(s.dim(`    Path:  ${o.path}`));const e=o.dataFiles,r=Object.entries(e).filter(([,o])=>o).map(([o])=>o),t=Object.entries(e).filter(([,o])=>!o).map(([o])=>o);console.log(`    Available: ${r.map(o=>s.green(o)).join(", ")||s.dim("none")}`),t.length>0&&console.log(`    Missing:   ${t.map(o=>s.dim(o)).join(", ")}`),console.log()}}else console.log(s.yellow("\n⚠ No Chrome profiles found.\n"))}z.command("browsers").description("List supported browsers and detect which are installed").option("--json","Output as JSON").action((o,e)=>I(F(e)));function G(o){const e=h({chromeDir:o.profilePath,profile:o.profile,search:o.search});if(x(o,e))return;if(0===e.length)return E("passwords",0);console.log(s.bold("\n🔑 Saved Passwords:\n"));const r=new Set(e.map(o=>o.profile)).size>1,t=["Source","URL","Username","Password","Last Used"],i=[9,42,24,22,20];r&&(t.unshift("Profile"),i.unshift(12));const n=R(t,i);for(const o of e){const e=[s.blue(o.source??"?"),s.cyan(o.url),s.green(o.username||"<empty>"),s.yellow(o.password||"<empty>"),s.dim(o.lastUsed)];r&&e.unshift(s.magenta(o.profile)),n.push(e)}console.log(n.toString()),E("password(s)",e.length)}T(M(z.command("passwords").description("List saved passwords"))).action((o,e)=>W(G,F(e)));function _(o){const e=u({chromeDir:o.profilePath,profile:o.profile,folder:o.folder,search:o.search});if(x(o,e))return;if(0===e.length)return E("bookmarks",0);console.log(s.bold("\n📚 Bookmarks:\n"));const r=R(["Title","URL","Folder","Date Added"],[30,50,25,20]);for(const o of e)r.push([s.white(o.title),s.cyan(o.url),s.dim(o.folder||"/"),s.dim(o.dateAdded)]);console.log(r.toString()),E("bookmark(s)",e.length)}T(M(z.command("bookmarks").description("List bookmarks"))).option("--folder <name>","Filter by folder name").action((o,e)=>W(_,F(e)));T(A(M(z.command("history").description("List browsing history")))).action((o,e)=>W(o=>{const e=g({chromeDir:o.profilePath,profile:o.profile,search:o.search,limit:parseInt(o.limit,10)||100});if(x(o,e))return;if(0===e.length)return E("history entries",0);console.log(s.bold("\n🕐 Browsing History:\n"));const r=R(["URL","Title","Visits","Last Visit"],[50,30,8,22]);for(const o of e)r.push([s.cyan(o.url),s.white(o.title||"—"),s.yellow(String(o.visitCount)),s.dim(o.lastVisit)]);console.log(r.toString()),E("history entry(ies)",e.length)},F(e)));A(M(z.command("search-terms").description("List search terms from history"))).action((o,e)=>W(o=>{const e=w({chromeDir:o.profilePath,profile:o.profile,limit:parseInt(o.limit,10)||100});if(x(o,e))return;if(0===e.length)return E("search terms",0);console.log(s.bold("\n🔍 Search Terms:\n"));const r=R(["Term","URL"],[40,80]);for(const o of e)r.push([s.white(o.term),s.dim(o.url)]);console.log(r.toString()),E("search term(s)",e.length)},F(e)));A(M(z.command("cookies").description("List cookies (encrypted values decrypted)"))).option("--domain <domain>","Filter by domain").option("--url <url>","Filter by URL with path").option("--no-decrypt","Skip decryption of encrypted values").action((o,e)=>W(o=>{const e=b({chromeDir:o.profilePath,profile:o.profile,domain:o.domain,url:o.url,decrypt:!1!==o.decrypt,limit:parseInt(o.limit,10)||100});if(x(o,e))return;if(0===e.length)return E("cookies",0);console.log(s.bold("\n🍪 Cookies:\n"));const r=R(["Domain","Name","Value","Secure","Expires"],[30,25,30,8,22]);for(const o of e)r.push([s.cyan(o.domain),s.white(o.name),s.dim(o.value?o.value.substring(0,50)+(o.value.length>50?"…":""):"—"),o.secure?s.green("✓"):s.dim("✗"),s.dim(o.expires)]);console.log(r.toString()),E("cookie(s)",e.length)},F(e)));function Y(o){const e=y({chromeDir:o.profilePath,profile:o.profile,origin:o.origin,url:o.url,key:o.key,search:o.search,limit:parseInt(o.limit,10)||100});if(x(o,e))return;if(0===e.length)return E("localStorage entries",0);console.log(s.bold("\n💾 localStorage:\n"));const r=R(["Origin","Key","Value"],[36,28,46]);for(const o of e)r.push([s.cyan(o.origin),s.white(o.key),s.dim(o.value?o.value.substring(0,80)+(o.value.length>80?"…":""):"—")]);console.log(r.toString()),E("localStorage entries",e.length)}T(A(M(z.command("local-storage").description("List localStorage entries")))).option("--origin <origin>","Filter by origin").option("--url <url>","Filter by URL origin").option("--key <key>","Filter by localStorage key").action((o,e)=>W(Y,F(e)));T(A(M(z.command("autofill").description("List autofill entries")))).action((o,e)=>W(o=>{const e=S({chromeDir:o.profilePath,profile:o.profile,search:o.search,limit:parseInt(o.limit,10)||100});if(x(o,e))return;if(0===e.length)return E("autofill entries",0);console.log(s.bold("\n📝 Autofill Entries:\n"));const r=R(["Field Name","Value","Count","Last Used"],[25,40,8,22]);for(const o of e)r.push([s.cyan(o.name),s.white(o.value),s.yellow(String(o.count)),s.dim(o.dateLastUsed)]);console.log(r.toString()),E("autofill entry(ies)",e.length)},F(e)));M(z.command("credit-cards").description("List saved credit cards")).action((o,e)=>W(o=>{const e=v({chromeDir:o.profilePath,profile:o.profile});if(x(o,e))return;if(0===e.length)return E("credit cards",0);console.log(s.bold("\n💳 Saved Credit Cards:\n"));const r=R(["Name on Card","Card Number","Expires","Nickname"],[25,25,14,20]);for(const o of e)r.push([s.white(o.nameOnCard||"—"),s.yellow(o.cardNumber||"—"),s.dim(`${o.expirationMonth}/${o.expirationYear}`),s.dim(o.nickname||"—")]);console.log(r.toString()),E("credit card(s)",e.length)},F(e)));M(z.command("addresses").description("List saved addresses")).action((o,e)=>W(o=>{const e=k({chromeDir:o.profilePath,profile:o.profile});if(x(o,e))return;if(0===e.length)return E("addresses",0);console.log(s.bold("\n🏠 Saved Addresses:\n"));const r=R(["Name","Email","Phone","Address","City/State/Zip"],[20,25,16,30,25]);for(const o of e)r.push([s.white(o.fullName||"—"),s.cyan(o.email||"—"),s.dim(o.phone||"—"),s.white(o.streetAddress||"—"),s.dim([o.city,o.state,o.zipcode].filter(Boolean).join(", ")||"—")]);console.log(r.toString()),E("address(es)",e.length)},F(e)));T(A(M(z.command("downloads").description("List download history")))).action((o,e)=>W(o=>{const e=L({chromeDir:o.profilePath,profile:o.profile,search:o.search,limit:parseInt(o.limit,10)||100});if(x(o,e))return;if(0===e.length)return E("downloads",0);console.log(s.bold("\n⬇️  Download History:\n"));const r=R(["File","URL","Size","State","Date"],[35,40,12,12,20]);for(const o of e){const e=o.targetPath?o.targetPath.split("/").pop():"—",t=o.totalBytes>0?Z(o.totalBytes):"—";r.push([s.white(e||""),s.cyan(o.url?o.url.substring(0,60):"—"),s.dim(t),"complete"===o.state?s.green(o.state):s.yellow(o.state),s.dim(o.startTime)])}console.log(r.toString()),E("download(s)",e.length)},F(e)));T(M(z.command("extensions").description("List installed extensions"))).action((o,e)=>W(o=>{const e=P({chromeDir:o.profilePath,profile:o.profile,search:o.search});if(x(o,e))return;if(0===e.length)return E("extensions",0);console.log(s.bold("\n🧩 Installed Extensions:\n"));const r=R(["Name","Version","ID","Enabled","Webstore"],[30,12,36,9,9]);for(const o of e)r.push([s.white(o.name),s.dim(o.version),s.dim(o.id),o.enabled?s.green("✓"):s.red("✗"),o.fromWebstore?s.green("✓"):s.dim("✗")]);console.log(r.toString()),E("extension(s)",e.length)},F(e)));M(z.command("search-engines").description("List configured search engines")).action((o,e)=>W(o=>{const e=D({chromeDir:o.profilePath,profile:o.profile});if(x(o,e))return;if(0===e.length)return E("search engines",0);console.log(s.bold("\n🔎 Search Engines:\n"));const r=R(["Name","Keyword","URL","Active"],[20,16,60,8]);for(const o of e)r.push([s.white(o.name),s.cyan(o.keyword),s.dim(o.url?o.url.substring(0,80):"—"),o.isActive?s.green("✓"):s.dim("✗")]);console.log(r.toString()),E("search engine(s)",e.length)},F(e)));function Z(o){if(0===o)return"0 B";const e=Math.floor(Math.log(o)/Math.log(1024));return`${(o/Math.pow(1024,e)).toFixed(1)} ${["B","KB","MB","GB","TB"][e]}`}M(z.command("top-sites").description("List top sites")).action((o,e)=>W(o=>{const e=j({chromeDir:o.profilePath,profile:o.profile});if(x(o,e))return;if(0===e.length)return E("top sites",0);console.log(s.bold("\n⭐ Top Sites:\n"));const r=R(["Rank","Title","URL"],[8,30,80]);for(const o of e)r.push([s.yellow(String(o.rank+1)),s.white(o.title||"—"),s.cyan(o.url)]);console.log(r.toString()),E("top site(s)",e.length)},F(e)));try{z.parse()}catch(o){(function(o){return!!f(o)&&(console.error(s.red.bold("\n🔑 No keychain access\n")),console.error(s.yellow("chrome-tools couldn't read the browser's encryption key from your macOS\nKeychain, so passwords and other encrypted data can't be decrypted.")),console.error(s.dim("\n"+o.message+"\n")),!0)})(o)||console.error(s.red(`\n✖ ${o?.message??String(o)}\n`)),process.env.DEBUG&&console.error(o),process.exit(1)}
+/**
+ * chrome-tools CLI
+ *
+ * A comprehensive command-line interface for extracting Chrome browser data on
+ * macOS, Windows, and Linux.
+ * Supports subcommands and shortcut flags for quick access to all data types.
+ */
+import { readFileSync } from "node:fs";
+import { Command, InvalidArgumentError } from "commander";
+import chalk from "chalk";
+import Table from "cli-table3";
+import { discoverProfiles, getProfileMetadata, getProfileStates, getDirectorySize, detectInstalledBrowsers } from "../src/core/chrome.js";
+import { setActiveBrowser, getActiveBrowser, isKeychainAccessDenied } from "../src/core/platform/index.js";
+import { getPasswords } from "../src/modules/passwords.js";
+import { getBookmarks } from "../src/modules/bookmarks.js";
+import { getHistory, getSearchTerms } from "../src/modules/history.js";
+import { getCookies } from "../src/modules/cookies.js";
+import { getLocalStorage } from "../src/modules/local-storage.js";
+import { getAutofillEntries, getCreditCards, getAddresses } from "../src/modules/autofill.js";
+import { getDownloads } from "../src/modules/downloads.js";
+import { getExtensions } from "../src/modules/extensions.js";
+import { getSearchEngines } from "../src/modules/search-engines.js";
+import { getTopSites } from "../src/modules/top-sites.js";
+// Resolved lazily per-invocation (inside handlers, after the active browser is
+// chosen) so `--browser` can drive the default profile path.
+const defaultProfilePath = process.env.PROFILE_PATH || undefined;
+const defaultProfileName = process.env.PROFILE_NAME || undefined;
+const defaultBrowser = process.env.BROWSER || process.env.CHROME_BROWSER || undefined;
+// ─── Output Helpers ──────────────────────────────────────────────────────────
+function outputJSON(data) {
+    console.log(JSON.stringify(data, null, 2));
+}
+function makeTable(headers, colWidths) {
+    return new Table({
+        head: headers.map((h) => chalk.bold.white(h)),
+        colWidths,
+        wordWrap: true,
+        style: { border: ["grey"], head: [] },
+    });
+}
+/**
+ * Prints a prominent, friendly "No keychain access" message for a denied/locked
+ * Keychain authorization. macOS itself shows the access prompt when we read the
+ * key — this explains what happened when that prompt is denied or unavailable.
+ * Returns true if the error was a keychain-access denial (and was handled here).
+ */
+function reportKeychainDenied(err) {
+    if (!isKeychainAccessDenied(err))
+        return false;
+    console.error(chalk.red.bold("\n🔑 No keychain access\n"));
+    console.error(chalk.yellow("chrome-tools couldn't read the browser's encryption key from your macOS\n" +
+        "Keychain, so passwords and other encrypted data can't be decrypted."));
+    // The typed error already carries actionable, cause-specific guidance.
+    console.error(chalk.dim("\n" + err.message + "\n"));
+    return true;
+}
+function printCount(label, count) {
+    if (count === 0) {
+        console.log(chalk.yellow(`\n⚠ No ${label} found.\n`));
+    }
+    else {
+        console.log(chalk.green(`\n✔ Found ${count} ${label}.\n`));
+    }
+}
+function renderResults(opts, results, title, label, headers, widths, toRow) {
+    if (emit(opts, results))
+        return;
+    if (results.length === 0)
+        return printCount(label, 0);
+    console.log(chalk.bold(`\n${title}:\n`));
+    const table = makeTable(headers, widths);
+    for (const result of results)
+        table.push(toRow(result));
+    console.log(table.toString());
+    printCount(label, results.length);
+}
+function errorMessage(err) {
+    return err instanceof Error ? err.message : String(err);
+}
+// When set (during `--all-browsers --json`), handlers route their JSON payload
+// here instead of printing, so we can emit a single combined document.
+let _jsonCollector = null;
+/**
+ * Emits a handler's results. Returns true when output was handled here (JSON or
+ * collected), letting the caller skip its human-readable table rendering.
+ */
+function emit(opts, results) {
+    if (_jsonCollector) {
+        _jsonCollector.push({ browser: getActiveBrowser().name, results });
+        return true;
+    }
+    if (opts.json) {
+        outputJSON(results);
+        return true;
+    }
+    return false;
+}
+/**
+ * Runs a single data handler for every installed Chromium browser, reusing the
+ * handler's own rendering. Human output gets a per-browser section header; JSON
+ * output is collected into one combined array.
+ */
+function runAll(handler, opts) {
+    const installed = detectInstalledBrowsers();
+    if (installed.length === 0) {
+        if (opts.json)
+            return outputJSON([]);
+        console.log(chalk.yellow("\n⚠ No supported Chromium browsers found on this machine.\n"));
+        return;
+    }
+    // --all-browsers spans browsers with different dirs, so a fixed --profile-path
+    // makes no sense; let each browser resolve its own default.
+    const perBrowserOpts = {
+        ...opts,
+        browser: undefined,
+        profilePath: undefined,
+    };
+    const previousBrowser = getActiveBrowser();
+    _jsonCollector = opts.json ? [] : null;
+    try {
+        for (const b of installed) {
+            setActiveBrowser(b.browser.id);
+            if (!opts.json) {
+                console.log(chalk.bold.magenta(`\n══════════ ${b.browser.name} ══════════`));
+            }
+            try {
+                handler(perBrowserOpts);
+            }
+            catch (err) {
+                if (_jsonCollector) {
+                    _jsonCollector.push({ browser: b.browser.name, results: { error: errorMessage(err) } });
+                }
+                else if (isKeychainAccessDenied(err)) {
+                    console.log(chalk.red(`  🔑 No keychain access — skipped (${err.service}).`));
+                    console.log(chalk.dim(`  ${err.message.split("\n").join("\n  ")}`));
+                }
+                else {
+                    console.log(chalk.red(`  ⚠ Skipped: ${errorMessage(err)}`));
+                }
+            }
+        }
+        if (_jsonCollector)
+            outputJSON(_jsonCollector);
+    }
+    finally {
+        _jsonCollector = null;
+        setActiveBrowser(previousBrowser.id);
+    }
+}
+/**
+ * Resolves the effective scope (browser + path + profile) from a command's
+ * options, applying environment fallbacks with the right precedence:
+ *
+ *   - A typed `--profile-path` / `--profile` always wins.
+ *   - When a browser is explicitly scoped (`--browser`, `--all-browsers`, or a
+ *     `BROWSER`/`CHROME_BROWSER` env var), the legacy `PROFILE_PATH` /
+ *     `PROFILE_NAME` env defaults are ignored — they point at one specific
+ *     Chrome dir and would otherwise mask the chosen browser's own location.
+ *   - Otherwise (the classic single-browser setup), `PROFILE_PATH` /
+ *     `PROFILE_NAME` apply as before.
+ */
+function scopeFromCli(cmd) {
+    const opts = cmd.optsWithGlobals();
+    const browserScoped = Boolean(opts.browser) || Boolean(opts.allBrowsers) || Boolean(defaultBrowser);
+    opts.browser = opts.browser || defaultBrowser || undefined;
+    if (!opts.profilePath) {
+        opts.profilePath = browserScoped ? undefined : defaultProfilePath;
+    }
+    if (!opts.profile) {
+        opts.profile = browserScoped ? undefined : defaultProfileName;
+    }
+    return opts;
+}
+/**
+ * Central entry point for data handlers: applies `--browser` (single) or fans
+ * out across `--all-browsers`.
+ */
+function dispatch(handler, opts) {
+    if (opts.allBrowsers) {
+        runAll(handler, opts);
+        return;
+    }
+    setActiveBrowser(opts.browser);
+    handler(opts);
+}
+// ─── Browsers Command ─────────────────────────────────────────────────────────
+function handleBrowsers(opts) {
+    const detected = detectInstalledBrowsers({ includeMissing: true });
+    if (opts.json) {
+        return outputJSON(detected.map((d) => ({
+            id: d.browser.id,
+            name: d.browser.name,
+            installed: d.installed,
+            profileCount: d.profileCount,
+            path: d.chromeDir,
+            safeStorageLabel: d.browser.safeStorageLabel,
+        })));
+    }
+    const installed = detected.filter((d) => d.installed);
+    console.log(chalk.bold(`\n🌐 Supported browsers (${installed.length} installed):\n`));
+    const table = makeTable(["Browser", "Id", "Installed", "Profiles", "Path"], [20, 14, 11, 9, 50]);
+    for (const d of detected) {
+        table.push([
+            chalk.white(d.browser.name),
+            chalk.cyan(d.browser.id),
+            d.installed ? chalk.green("✓") : chalk.dim("✗"),
+            d.installed ? chalk.yellow(String(d.profileCount)) : chalk.dim("—"),
+            chalk.dim(d.chromeDir),
+        ]);
+    }
+    console.log(table.toString());
+}
+// ─── Shared Options ──────────────────────────────────────────────────────────
+function addCommonOptions(cmd) {
+    return cmd
+        .option("--profile-path <path>", "Custom browser User Data Path (overrides --browser)")
+        .option("--profile <name>", "Target a specific profile")
+        .option("--browser <name>", "Browser to read (chrome, edge, brave, comet, vivaldi, opera, chromium…)")
+        .option("--all-browsers", "Read from every installed Chromium browser")
+        .option("--json", "Output as JSON");
+}
+function addSearchOption(cmd) {
+    return cmd.option("--search <term>", "Filter results (case-insensitive)");
+}
+function addLimitOption(cmd, defaultLimit = 100) {
+    return cmd.option("--limit <n>", "Limit number of results", parseLimit, defaultLimit);
+}
+function parseLimit(value) {
+    const limit = Number(value);
+    if (!Number.isSafeInteger(limit) || limit < 0) {
+        throw new InvalidArgumentError("Limit must be a non-negative integer.");
+    }
+    return limit;
+}
+// ─── Program Setup ───────────────────────────────────────────────────────────
+const program = new Command();
+const pkg = JSON.parse(readFileSync(new URL("../../package.json", import.meta.url), "utf8"));
+program
+    .name("chrome-tools")
+    .description(chalk.bold.cyan("Chrome Data Toolkit") +
+    chalk.dim(" — Extract passwords, bookmarks, history, cookies, and more from Chrome on macOS, Windows, and Linux"))
+    .version(pkg.version)
+    .option("--passwords", "Shortcut: list saved passwords")
+    .option("--bookmarks", "Shortcut: list bookmarks")
+    .option("--local-storage", "Shortcut: list localStorage entries")
+    .option("--profiles", "Shortcut: list profiles")
+    .option("--browsers", "Shortcut: list supported / installed browsers")
+    .option("--size", "Show each profile's size on disk when listing profiles (slower)");
+addCommonOptions(program)
+    .option("--search <term>", "Filter results (for shortcut flags)")
+    .option("--limit <n>", "Limit results (for shortcut flags)", parseLimit)
+    .action((opts, cmd) => {
+    // Default action when no subcommand is given.
+    const o = scopeFromCli(cmd);
+    if (o.browsers) {
+        handleBrowsers(o);
+    }
+    else if (o.passwords) {
+        dispatch(handlePasswords, o);
+    }
+    else if (o.bookmarks) {
+        dispatch(handleBookmarks, o);
+    }
+    else if (o.localStorage) {
+        dispatch(handleLocalStorage, o);
+    }
+    else {
+        // Default (including --profiles shortcut): list profiles.
+        dispatch(handleProfiles, o);
+    }
+});
+// ─── Profiles Command ───────────────────────────────────────────────────────
+const profilesCmd = program
+    .command("profiles")
+    .description("List Chrome profiles");
+addCommonOptions(profilesCmd)
+    .option("--size", "Compute and show each profile's size on disk (slower)")
+    .action((opts, cmd) => {
+    dispatch(handleProfiles, scopeFromCli(cmd));
+});
+const statesCmd = profilesCmd
+    .command("states")
+    .description("Show detailed profile states with available data files");
+addCommonOptions(statesCmd).action((opts, cmd) => dispatch(handleProfileStates, scopeFromCli(cmd)));
+// ─── Browsers Command ─────────────────────────────────────────────────────────
+const browsersCmd = program
+    .command("browsers")
+    .description("List supported browsers and detect which are installed");
+browsersCmd
+    .option("--json", "Output as JSON")
+    .action((opts, cmd) => handleBrowsers(scopeFromCli(cmd)));
+function handleProfiles(opts) {
+    const profiles = discoverProfiles(opts.profilePath);
+    const metadata = getProfileMetadata(opts.profilePath);
+    const withSize = Boolean(opts.size);
+    if (opts.json) {
+        const metaMap = new Map(metadata.map((m) => [m.directory, m]));
+        const enriched = profiles.map((p) => ({
+            ...p,
+            ...metaMap.get(p.name),
+            ...(withSize ? { sizeBytes: getDirectorySize(p.path) } : {}),
+        }));
+        emit(opts, enriched);
+        return;
+    }
+    if (profiles.length === 0) {
+        console.log(chalk.yellow("\n⚠ No Chrome profiles found.\n"));
+        return;
+    }
+    const metaMap = new Map(metadata.map((m) => [m.directory, m]));
+    console.log(chalk.bold(`\n📁 Discovered ${profiles.length} profile(s):\n`));
+    const headers = withSize
+        ? ["Directory", "Display Name", "Email", "Size", "Path"]
+        : ["Directory", "Display Name", "Email", "Path"];
+    const widths = withSize ? [16, 22, 30, 10, 42] : [16, 22, 30, 50];
+    const table = makeTable(headers, widths);
+    for (const p of profiles) {
+        const meta = metaMap.get(p.name);
+        const row = [
+            chalk.cyan(p.name),
+            chalk.white(meta?.name || p.name),
+            chalk.dim(meta?.email || "—"),
+        ];
+        if (withSize) {
+            row.push(chalk.yellow(formatBytes(getDirectorySize(p.path))));
+        }
+        row.push(chalk.dim(p.path));
+        table.push(row);
+    }
+    console.log(table.toString());
+    printCount("profile(s)", profiles.length);
+}
+function handleProfileStates(opts) {
+    const states = getProfileStates(opts.profilePath);
+    if (opts.json) {
+        emit(opts, states);
+        return;
+    }
+    if (states.length === 0) {
+        console.log(chalk.yellow("\n⚠ No Chrome profiles found.\n"));
+        return;
+    }
+    console.log(chalk.bold(`\n📊 Profile States (${states.length} profile(s)):\n`));
+    for (const state of states) {
+        console.log(chalk.bold.cyan(`  ${state.displayName}`) + chalk.dim(` (${state.directory})`));
+        if (state.email) {
+            console.log(chalk.dim(`    Email: ${state.email}`));
+        }
+        console.log(chalk.dim(`    Path:  ${state.path}`));
+        const files = state.dataFiles;
+        const available = Object.entries(files)
+            .filter(([, exists]) => exists)
+            .map(([name]) => name);
+        const missing = Object.entries(files)
+            .filter(([, exists]) => !exists)
+            .map(([name]) => name);
+        console.log(`    Available: ${available.map((f) => chalk.green(f)).join(", ") || chalk.dim("none")}`);
+        if (missing.length > 0) {
+            console.log(`    Missing:   ${missing.map((f) => chalk.dim(f)).join(", ")}`);
+        }
+        console.log();
+    }
+}
+// ─── Passwords Command ──────────────────────────────────────────────────────
+const passwordsCmd = program.command("passwords").description("List saved passwords");
+addSearchOption(addCommonOptions(passwordsCmd)).action((opts, cmd) => dispatch(handlePasswords, scopeFromCli(cmd)));
+function handlePasswords(opts) {
+    const results = getPasswords(opts);
+    if (emit(opts, results))
+        return;
+    if (results.length === 0) {
+        return printCount("passwords", 0);
+    }
+    console.log(chalk.bold("\n🔑 Saved Passwords:\n"));
+    const showProfile = new Set(results.map((r) => r.profile)).size > 1;
+    // Always show the source (device vs account) — it explains where each entry
+    // lives and why a device-only listing can look empty when sync is on.
+    const head = ["Source", "URL", "Username", "Password", "Last Used"];
+    const widths = [9, 42, 24, 22, 20];
+    if (showProfile) {
+        head.unshift("Profile");
+        widths.unshift(12);
+    }
+    const table = makeTable(head, widths);
+    for (const r of results) {
+        const row = [
+            chalk.blue(r.source ?? "?"),
+            chalk.cyan(r.url),
+            chalk.green(r.username || "<empty>"),
+            chalk.yellow(r.password || "<empty>"),
+            chalk.dim(r.lastUsed),
+        ];
+        if (showProfile)
+            row.unshift(chalk.magenta(r.profile));
+        table.push(row);
+    }
+    console.log(table.toString());
+    printCount("password(s)", results.length);
+}
+// ─── Bookmarks Command ──────────────────────────────────────────────────────
+const bookmarksCmd = program.command("bookmarks").description("List bookmarks");
+addSearchOption(addCommonOptions(bookmarksCmd))
+    .option("--folder <name>", "Filter by folder name")
+    .action((opts, cmd) => dispatch(handleBookmarks, scopeFromCli(cmd)));
+function handleBookmarks(opts) {
+    renderResults(opts, getBookmarks(opts), "📚 Bookmarks", "bookmark(s)", ["Title", "URL", "Folder", "Date Added"], [30, 50, 25, 20], (r) => [
+        chalk.white(r.title),
+        chalk.cyan(r.url),
+        chalk.dim(r.folder || "/"),
+        chalk.dim(r.dateAdded),
+    ]);
+}
+// ─── History Command ─────────────────────────────────────────────────────────
+const historyCmd = program.command("history").description("List browsing history");
+addSearchOption(addLimitOption(addCommonOptions(historyCmd))).action((opts, cmd) => dispatch((mergedOpts) => {
+    renderResults(mergedOpts, getHistory(mergedOpts), "🕐 Browsing History", "history entry(ies)", ["URL", "Title", "Visits", "Last Visit"], [50, 30, 8, 22], (r) => [
+        chalk.cyan(r.url),
+        chalk.white(r.title || "—"),
+        chalk.yellow(String(r.visitCount)),
+        chalk.dim(r.lastVisit),
+    ]);
+}, scopeFromCli(cmd)));
+// ─── Search Terms Command ────────────────────────────────────────────────────
+const searchTermsCmd = program.command("search-terms").description("List search terms from history");
+addLimitOption(addCommonOptions(searchTermsCmd)).action((opts, cmd) => dispatch((mergedOpts) => {
+    renderResults(mergedOpts, getSearchTerms(mergedOpts), "🔍 Search Terms", "search term(s)", ["Term", "URL"], [40, 80], (r) => [chalk.white(r.term), chalk.dim(r.url)]);
+}, scopeFromCli(cmd)));
+// ─── Cookies Command ─────────────────────────────────────────────────────────
+const cookiesCmd = program.command("cookies").description("List cookies (encrypted values decrypted)");
+addLimitOption(addCommonOptions(cookiesCmd))
+    .option("--domain <domain>", "Filter by domain")
+    .option("--url <url>", "Filter by URL with path")
+    .option("--no-decrypt", "Skip decryption of encrypted values")
+    .action((opts, cmd) => dispatch((mergedOpts) => {
+    renderResults(mergedOpts, getCookies(mergedOpts), "🍪 Cookies", "cookie(s)", ["Domain", "Name", "Value", "Secure", "Expires"], [30, 25, 30, 8, 22], (r) => [
+        chalk.cyan(r.domain),
+        chalk.white(r.name),
+        chalk.dim(truncate(r.value, 50)),
+        r.secure ? chalk.green("✓") : chalk.dim("✗"),
+        chalk.dim(r.expires),
+    ]);
+}, scopeFromCli(cmd)));
+// ─── Local Storage Command ──────────────────────────────────────────────────
+const localStorageCmd = program.command("local-storage").description("List localStorage entries");
+addSearchOption(addLimitOption(addCommonOptions(localStorageCmd)))
+    .option("--origin <origin>", "Filter by origin")
+    .option("--url <url>", "Filter by URL origin")
+    .option("--key <key>", "Filter by localStorage key")
+    .action((opts, cmd) => dispatch(handleLocalStorage, scopeFromCli(cmd)));
+function handleLocalStorage(opts) {
+    renderResults(opts, getLocalStorage(opts), "💾 localStorage", "localStorage entries", ["Origin", "Key", "Value"], [36, 28, 46], (r) => [
+        chalk.cyan(r.origin),
+        chalk.white(r.key),
+        chalk.dim(truncate(r.value, 80)),
+    ]);
+}
+// ─── Autofill Command ────────────────────────────────────────────────────────
+const autofillCmd = program.command("autofill").description("List autofill entries");
+addSearchOption(addLimitOption(addCommonOptions(autofillCmd))).action((opts, cmd) => dispatch((mergedOpts) => {
+    renderResults(mergedOpts, getAutofillEntries(mergedOpts), "📝 Autofill Entries", "autofill entry(ies)", ["Field Name", "Value", "Count", "Last Used"], [25, 40, 8, 22], (r) => [
+        chalk.cyan(r.name),
+        chalk.white(r.value),
+        chalk.yellow(String(r.count)),
+        chalk.dim(r.dateLastUsed),
+    ]);
+}, scopeFromCli(cmd)));
+// ─── Credit Cards Command ────────────────────────────────────────────────────
+const creditCardsCmd = program.command("credit-cards").description("List saved credit cards");
+addCommonOptions(creditCardsCmd).action((opts, cmd) => dispatch((mergedOpts) => {
+    renderResults(mergedOpts, getCreditCards(mergedOpts), "💳 Saved Credit Cards", "credit card(s)", ["Name on Card", "Card Number", "Expires", "Nickname"], [25, 25, 14, 20], (r) => [
+        chalk.white(r.nameOnCard || "—"),
+        chalk.yellow(r.cardNumber || "—"),
+        chalk.dim(`${r.expirationMonth}/${r.expirationYear}`),
+        chalk.dim(r.nickname || "—"),
+    ]);
+}, scopeFromCli(cmd)));
+// ─── Addresses Command ───────────────────────────────────────────────────────
+const addressesCmd = program.command("addresses").description("List saved addresses");
+addCommonOptions(addressesCmd).action((opts, cmd) => dispatch((mergedOpts) => {
+    renderResults(mergedOpts, getAddresses(mergedOpts), "🏠 Saved Addresses", "address(es)", ["Name", "Email", "Phone", "Address", "City/State/Zip"], [20, 25, 16, 30, 25], (r) => [
+        chalk.white(r.fullName || "—"),
+        chalk.cyan(r.email || "—"),
+        chalk.dim(r.phone || "—"),
+        chalk.white(r.streetAddress || "—"),
+        chalk.dim([r.city, r.state, r.zipcode].filter(Boolean).join(", ") || "—"),
+    ]);
+}, scopeFromCli(cmd)));
+// ─── Downloads Command ───────────────────────────────────────────────────────
+const downloadsCmd = program.command("downloads").description("List download history");
+addSearchOption(addLimitOption(addCommonOptions(downloadsCmd))).action((opts, cmd) => dispatch((mergedOpts) => {
+    renderResults(mergedOpts, getDownloads(mergedOpts), "⬇️  Download History", "download(s)", ["File", "URL", "Size", "State", "Date"], [35, 40, 12, 12, 20], (r) => [
+        chalk.white(r.targetPath ? r.targetPath.split(/[\\/]/).pop() || "" : "—"),
+        chalk.cyan(truncate(r.url, 60)),
+        chalk.dim(r.totalBytes > 0 ? formatBytes(r.totalBytes) : "—"),
+        r.state === "complete" ? chalk.green(r.state) : chalk.yellow(r.state),
+        chalk.dim(r.startTime),
+    ]);
+}, scopeFromCli(cmd)));
+// ─── Extensions Command ─────────────────────────────────────────────────────
+const extensionsCmd = program.command("extensions").description("List installed extensions");
+addSearchOption(addCommonOptions(extensionsCmd)).action((opts, cmd) => dispatch((mergedOpts) => {
+    renderResults(mergedOpts, getExtensions(mergedOpts), "🧩 Installed Extensions", "extension(s)", ["Name", "Version", "ID", "Enabled", "Webstore"], [30, 12, 36, 9, 9], (r) => [
+        chalk.white(r.name),
+        chalk.dim(r.version),
+        chalk.dim(r.id),
+        r.enabled ? chalk.green("✓") : chalk.red("✗"),
+        r.fromWebstore ? chalk.green("✓") : chalk.dim("✗"),
+    ]);
+}, scopeFromCli(cmd)));
+// ─── Search Engines Command ─────────────────────────────────────────────────
+const searchEnginesCmd = program.command("search-engines").description("List configured search engines");
+addCommonOptions(searchEnginesCmd).action((opts, cmd) => dispatch((mergedOpts) => {
+    renderResults(mergedOpts, getSearchEngines(mergedOpts), "🔎 Search Engines", "search engine(s)", ["Name", "Keyword", "URL", "Active"], [20, 16, 60, 8], (r) => [
+        chalk.white(r.name),
+        chalk.cyan(r.keyword),
+        chalk.dim(truncate(r.url, 80)),
+        r.isActive ? chalk.green("✓") : chalk.dim("✗"),
+    ]);
+}, scopeFromCli(cmd)));
+// ─── Top Sites Command ──────────────────────────────────────────────────────
+const topSitesCmd = program.command("top-sites").description("List top sites");
+addCommonOptions(topSitesCmd).action((opts, cmd) => dispatch((mergedOpts) => {
+    renderResults(mergedOpts, getTopSites(mergedOpts), "⭐ Top Sites", "top site(s)", ["Rank", "Title", "URL"], [8, 30, 80], (r) => [
+        chalk.yellow(String(r.rank + 1)),
+        chalk.white(r.title || "—"),
+        chalk.cyan(r.url),
+    ]);
+}, scopeFromCli(cmd)));
+// ─── Utilities ───────────────────────────────────────────────────────────────
+function formatBytes(bytes) {
+    if (bytes === 0)
+        return "0 B";
+    const units = ["B", "KB", "MB", "GB", "TB"];
+    const i = Math.floor(Math.log(bytes) / Math.log(1024));
+    return `${(bytes / Math.pow(1024, i)).toFixed(1)} ${units[i]}`;
+}
+function truncate(value, maxLength) {
+    if (!value)
+        return "—";
+    return value.length > maxLength ? value.slice(0, maxLength) + "…" : value;
+}
+// ─── Run ─────────────────────────────────────────────────────────────────────
+try {
+    program.parse();
+}
+catch (err) {
+    // Print a clean, actionable message instead of dumping the minified source and
+    // a Node stack trace for expected failures (bad --browser, keychain denial, …).
+    // Set DEBUG=1 to see the full stack.
+    if (!reportKeychainDenied(err)) {
+        console.error(chalk.red(`\n✖ ${errorMessage(err)}\n`));
+    }
+    if (process.env.DEBUG)
+        console.error(err);
+    process.exit(1);
+}

package/dist/src/core/browsers.d.ts

@@ -10,16 +10,18 @@
  *      Linux Secret Service application).
  *
  * "Browser" is therefore a small dimension orthogonal to "platform": the
- * platform backends (darwin/win32/linux) read the active browser's dir + label
- * from here and stay otherwise unchanged.
+ * platform backends (darwin/win32/linux) receive a browser descriptor and stay
+ * otherwise unchanged.
  */
 export type BrowserId = "chrome" | "chrome-beta" | "chrome-canary" | "chromium" | "edge" | "brave" | "comet" | "vivaldi" | "opera";
 /** Subpaths to a browser's User Data dir, relative to each OS's app-data base. */
 export interface BrowserDirs {
     /** Under `~/Library/Application Support`. */
     darwin: string;
-    /** Under `%LOCALAPPDATA%`. Includes the trailing `User Data` segment. */
+    /** Under the selected Windows app-data root. Includes any `User Data` segment. */
     win32: string;
+    /** Windows application-data root. Chromium browsers normally use Local. */
+    win32Base?: "local" | "roaming";
     /** Under `$XDG_CONFIG_HOME` (or `~/.config`). */
     linux: string;
 }
@@ -53,6 +55,8 @@ export declare function listBrowsers(): BrowserDescriptor[];
  * @returns The descriptor, or `null` if unrecognized.
  */
 export declare function resolveBrowser(idOrName: string): BrowserDescriptor | null;
+/** Resolves a browser or throws an actionable error without changing global state. */
+export declare function requireBrowser(idOrName: string): BrowserDescriptor;
 /** The browser currently targeted by dir/key lookups. Defaults to Chrome. */
 export declare function getActiveBrowser(): BrowserDescriptor;
 /**