chrome-tools 1.0.1

package/bin/cli.js

@@ -0,0 +1,590 @@
+#!/usr/bin/env node
+
+/**
+ * chrome-tools CLI
+ *
+ * A comprehensive command-line interface for extracting Chrome browser data on macOS.
+ * Supports subcommands and shortcut flags for quick access to all data types.
+ */
+
+import { Command } from "commander";
+import chalk from "chalk";
+import Table from "cli-table3";
+
+import { discoverProfiles, getProfileMetadata, getProfileStates } from "../src/core/chrome.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 { 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";
+
+// ─── 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: [] },
+  });
+}
+
+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`));
+  }
+}
+
+// ─── Shared Options ──────────────────────────────────────────────────────────
+
+function addCommonOptions(cmd) {
+  return cmd
+    .option("--chrome-dir <path>", "Custom Chrome User Data directory")
+    .option("--profile <name>", "Target a specific profile")
+    .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", String(defaultLimit));
+}
+
+// ─── Program Setup ───────────────────────────────────────────────────────────
+
+const program = new Command();
+
+program
+  .name("chrome-tools")
+  .description(
+    chalk.bold.cyan("Chrome Data Toolkit") +
+    chalk.dim(" — Extract passwords, bookmarks, history, cookies, and more from Chrome on macOS")
+  )
+  .version("1.0.0")
+  .option("--passwords", "Shortcut: list saved passwords")
+  .option("--bookmarks", "Shortcut: list bookmarks")
+  .option("--profiles", "Shortcut: list profiles")
+  .option("--chrome-dir <path>", "Custom Chrome User Data directory")
+  .option("--profile <name>", "Target a specific profile")
+  .option("--json", "Output as JSON")
+  .option("--search <term>", "Filter results (for shortcut flags)")
+  .option("--limit <n>", "Limit results (for shortcut flags)")
+  .action((opts) => {
+    // Handle shortcut flags at the top level
+    if (opts.passwords) {
+      return handlePasswords(opts);
+    }
+    if (opts.bookmarks) {
+      return handleBookmarks(opts);
+    }
+    if (opts.profiles) {
+      return handleProfiles(opts);
+    }
+    // No shortcut flag — show help
+    program.help();
+  });
+
+// ─── Profiles Command ───────────────────────────────────────────────────────
+
+const profilesCmd = program
+  .command("profiles")
+  .description("List Chrome profiles");
+
+addCommonOptions(profilesCmd).action((opts, cmd) => {
+  handleProfiles(cmd.optsWithGlobals());
+});
+
+profilesCmd
+  .command("states")
+  .description("Show detailed profile states with available data files")
+  .option("--chrome-dir <path>", "Custom Chrome User Data directory")
+  .option("--json", "Output as JSON")
+  .action((opts, cmd) => handleProfileStates(cmd.optsWithGlobals()));
+
+function handleProfiles(opts) {
+  const profiles = discoverProfiles(opts.chromeDir);
+  const metadata = getProfileMetadata(opts.chromeDir);
+
+  if (opts.json) {
+    const metaMap = new Map(metadata.map((m) => [m.directory, m]));
+    const enriched = profiles.map((p) => ({
+      ...p,
+      ...(metaMap.get(p.name) || {}),
+    }));
+    return outputJSON(enriched);
+  }
+
+  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 table = makeTable(["Directory", "Display Name", "Email", "Path"], [16, 22, 30, 50]);
+
+  for (const p of profiles) {
+    const meta = metaMap.get(p.name) || {};
+    table.push([
+      chalk.cyan(p.name),
+      chalk.white(meta.name || p.name),
+      chalk.dim(meta.email || "—"),
+      chalk.dim(p.path),
+    ]);
+  }
+  console.log(table.toString());
+  printCount("profile(s)", profiles.length);
+}
+
+function handleProfileStates(opts) {
+  const states = getProfileStates(opts.chromeDir);
+
+  if (opts.json) {
+    return outputJSON(states);
+  }
+
+  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");
+addCommonOptions(addSearchOption(passwordsCmd)).action((opts, cmd) => handlePasswords(cmd.optsWithGlobals()));
+
+function handlePasswords(opts) {
+  const results = getPasswords({
+    chromeDir: opts.chromeDir,
+    profile: opts.profile,
+    search: opts.search,
+  });
+
+  if (opts.json) return outputJSON(results);
+
+  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;
+  const head = showProfile
+    ? ["Profile", "URL", "Username", "Password", "Last Used"]
+    : ["URL", "Username", "Password", "Last Used"];
+  const widths = showProfile ? [12, 40, 24, 22, 20] : [45, 28, 25, 22];
+
+  const table = makeTable(head, widths);
+  for (const r of results) {
+    const row = [
+      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");
+addCommonOptions(addSearchOption(bookmarksCmd))
+  .option("--folder <name>", "Filter by folder name")
+  .action((opts, cmd) => handleBookmarks(cmd.optsWithGlobals()));
+
+function handleBookmarks(opts) {
+  const results = getBookmarks({
+    chromeDir: opts.chromeDir,
+    profile: opts.profile,
+    folder: opts.folder,
+    search: opts.search,
+  });
+
+  if (opts.json) return outputJSON(results);
+
+  if (results.length === 0) {
+    return printCount("bookmarks", 0);
+  }
+
+  console.log(chalk.bold("\n📚 Bookmarks:\n"));
+  const table = makeTable(["Title", "URL", "Folder", "Date Added"], [30, 50, 25, 20]);
+  for (const r of results) {
+    table.push([
+      chalk.white(r.title),
+      chalk.cyan(r.url),
+      chalk.dim(r.folder || "/"),
+      chalk.dim(r.dateAdded),
+    ]);
+  }
+  console.log(table.toString());
+  printCount("bookmark(s)", results.length);
+}
+
+// ─── History Command ─────────────────────────────────────────────────────────
+
+const historyCmd = program.command("history").description("List browsing history");
+addCommonOptions(addSearchOption(addLimitOption(historyCmd))).action((opts, cmd) => {
+  const mergedOpts = cmd.optsWithGlobals();
+  const results = getHistory({
+    chromeDir: mergedOpts.chromeDir,
+    profile: mergedOpts.profile,
+    search: mergedOpts.search,
+    limit: parseInt(mergedOpts.limit, 10) || 100,
+  });
+
+  if (mergedOpts.json) return outputJSON(results);
+
+  if (results.length === 0) {
+    return printCount("history entries", 0);
+  }
+
+  console.log(chalk.bold("\n🕐 Browsing History:\n"));
+  const table = makeTable(["URL", "Title", "Visits", "Last Visit"], [50, 30, 8, 22]);
+  for (const r of results) {
+    table.push([
+      chalk.cyan(r.url),
+      chalk.white(r.title || "—"),
+      chalk.yellow(String(r.visitCount)),
+      chalk.dim(r.lastVisit),
+    ]);
+  }
+  console.log(table.toString());
+  printCount("history entry(ies)", results.length);
+});
+
+// ─── Search Terms Command ────────────────────────────────────────────────────
+
+const searchTermsCmd = program.command("search-terms").description("List search terms from history");
+addCommonOptions(addLimitOption(searchTermsCmd)).action((opts, cmd) => {
+  const mergedOpts = cmd.optsWithGlobals();
+  const results = getSearchTerms({
+    chromeDir: mergedOpts.chromeDir,
+    profile: mergedOpts.profile,
+    limit: parseInt(mergedOpts.limit, 10) || 100,
+  });
+
+  if (mergedOpts.json) return outputJSON(results);
+
+  if (results.length === 0) {
+    return printCount("search terms", 0);
+  }
+
+  console.log(chalk.bold("\n🔍 Search Terms:\n"));
+  const table = makeTable(["Term", "URL"], [40, 80]);
+  for (const r of results) {
+    table.push([chalk.white(r.term), chalk.dim(r.url)]);
+  }
+  console.log(table.toString());
+  printCount("search term(s)", results.length);
+});
+
+// ─── Cookies Command ─────────────────────────────────────────────────────────
+
+const cookiesCmd = program.command("cookies").description("List cookies (encrypted values decrypted)");
+addCommonOptions(addLimitOption(cookiesCmd))
+  .option("--domain <domain>", "Filter by domain")
+  .option("--no-decrypt", "Skip decryption of encrypted values")
+  .action((opts, cmd) => {
+    const mergedOpts = cmd.optsWithGlobals();
+    const results = getCookies({
+      chromeDir: mergedOpts.chromeDir,
+      profile: mergedOpts.profile,
+      domain: mergedOpts.domain,
+      decrypt: mergedOpts.decrypt !== false,
+      limit: parseInt(mergedOpts.limit, 10) || 100,
+    });
+
+    if (mergedOpts.json) return outputJSON(results);
+
+    if (results.length === 0) {
+      return printCount("cookies", 0);
+    }
+
+    console.log(chalk.bold("\n🍪 Cookies:\n"));
+    const table = makeTable(["Domain", "Name", "Value", "Secure", "Expires"], [30, 25, 30, 8, 22]);
+    for (const r of results) {
+      table.push([
+        chalk.cyan(r.domain),
+        chalk.white(r.name),
+        chalk.dim(r.value ? r.value.substring(0, 50) + (r.value.length > 50 ? "…" : "") : "—"),
+        r.secure ? chalk.green("✓") : chalk.dim("✗"),
+        chalk.dim(r.expires),
+      ]);
+    }
+    console.log(table.toString());
+    printCount("cookie(s)", results.length);
+  });
+
+// ─── Autofill Command ────────────────────────────────────────────────────────
+
+const autofillCmd = program.command("autofill").description("List autofill entries");
+addCommonOptions(addSearchOption(addLimitOption(autofillCmd))).action((opts, cmd) => {
+  const mergedOpts = cmd.optsWithGlobals();
+  const results = getAutofillEntries({
+    chromeDir: mergedOpts.chromeDir,
+    profile: mergedOpts.profile,
+    search: mergedOpts.search,
+    limit: parseInt(mergedOpts.limit, 10) || 100,
+  });
+
+  if (mergedOpts.json) return outputJSON(results);
+
+  if (results.length === 0) {
+    return printCount("autofill entries", 0);
+  }
+
+  console.log(chalk.bold("\n📝 Autofill Entries:\n"));
+  const table = makeTable(["Field Name", "Value", "Count", "Last Used"], [25, 40, 8, 22]);
+  for (const r of results) {
+    table.push([
+      chalk.cyan(r.name),
+      chalk.white(r.value),
+      chalk.yellow(String(r.count)),
+      chalk.dim(r.dateLastUsed),
+    ]);
+  }
+  console.log(table.toString());
+  printCount("autofill entry(ies)", results.length);
+});
+
+// ─── Credit Cards Command ────────────────────────────────────────────────────
+
+const creditCardsCmd = program.command("credit-cards").description("List saved credit cards");
+addCommonOptions(creditCardsCmd).action((opts, cmd) => {
+  const mergedOpts = cmd.optsWithGlobals();
+  const results = getCreditCards({
+    chromeDir: mergedOpts.chromeDir,
+    profile: mergedOpts.profile,
+  });
+
+  if (mergedOpts.json) return outputJSON(results);
+
+  if (results.length === 0) {
+    return printCount("credit cards", 0);
+  }
+
+  console.log(chalk.bold("\n💳 Saved Credit Cards:\n"));
+  const table = makeTable(["Name on Card", "Card Number", "Expires", "Nickname"], [25, 25, 14, 20]);
+  for (const r of results) {
+    table.push([
+      chalk.white(r.nameOnCard || "—"),
+      chalk.yellow(r.cardNumber || "—"),
+      chalk.dim(`${r.expirationMonth}/${r.expirationYear}`),
+      chalk.dim(r.nickname || "—"),
+    ]);
+  }
+  console.log(table.toString());
+  printCount("credit card(s)", results.length);
+});
+
+// ─── Addresses Command ───────────────────────────────────────────────────────
+
+const addressesCmd = program.command("addresses").description("List saved addresses");
+addCommonOptions(addressesCmd).action((opts, cmd) => {
+  const mergedOpts = cmd.optsWithGlobals();
+  const results = getAddresses({
+    chromeDir: mergedOpts.chromeDir,
+    profile: mergedOpts.profile,
+  });
+
+  if (mergedOpts.json) return outputJSON(results);
+
+  if (results.length === 0) {
+    return printCount("addresses", 0);
+  }
+
+  console.log(chalk.bold("\n🏠 Saved Addresses:\n"));
+  const table = makeTable(["Name", "Email", "Phone", "Address", "City/State/Zip"], [20, 25, 16, 30, 25]);
+  for (const r of results) {
+    table.push([
+      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(", ") || "—"),
+    ]);
+  }
+  console.log(table.toString());
+  printCount("address(es)", results.length);
+});
+
+// ─── Downloads Command ───────────────────────────────────────────────────────
+
+const downloadsCmd = program.command("downloads").description("List download history");
+addCommonOptions(addSearchOption(addLimitOption(downloadsCmd))).action((opts, cmd) => {
+  const mergedOpts = cmd.optsWithGlobals();
+  const results = getDownloads({
+    chromeDir: mergedOpts.chromeDir,
+    profile: mergedOpts.profile,
+    search: mergedOpts.search,
+    limit: parseInt(mergedOpts.limit, 10) || 100,
+  });
+
+  if (mergedOpts.json) return outputJSON(results);
+
+  if (results.length === 0) {
+    return printCount("downloads", 0);
+  }
+
+  console.log(chalk.bold("\n⬇️  Download History:\n"));
+  const table = makeTable(["File", "URL", "Size", "State", "Date"], [35, 40, 12, 12, 20]);
+  for (const r of results) {
+    const filename = r.targetPath ? r.targetPath.split("/").pop() : "—";
+    const sizeStr = r.totalBytes > 0 ? formatBytes(r.totalBytes) : "—";
+    table.push([
+      chalk.white(filename),
+      chalk.cyan(r.url ? r.url.substring(0, 60) : "—"),
+      chalk.dim(sizeStr),
+      r.state === "complete" ? chalk.green(r.state) : chalk.yellow(r.state),
+      chalk.dim(r.startTime),
+    ]);
+  }
+  console.log(table.toString());
+  printCount("download(s)", results.length);
+});
+
+// ─── Extensions Command ─────────────────────────────────────────────────────
+
+const extensionsCmd = program.command("extensions").description("List installed extensions");
+addCommonOptions(addSearchOption(extensionsCmd)).action((opts, cmd) => {
+  const mergedOpts = cmd.optsWithGlobals();
+  const results = getExtensions({
+    chromeDir: mergedOpts.chromeDir,
+    profile: mergedOpts.profile,
+    search: mergedOpts.search,
+  });
+
+  if (mergedOpts.json) return outputJSON(results);
+
+  if (results.length === 0) {
+    return printCount("extensions", 0);
+  }
+
+  console.log(chalk.bold("\n🧩 Installed Extensions:\n"));
+  const table = makeTable(["Name", "Version", "ID", "Enabled", "Webstore"], [30, 12, 36, 9, 9]);
+  for (const r of results) {
+    table.push([
+      chalk.white(r.name),
+      chalk.dim(r.version),
+      chalk.dim(r.id),
+      r.enabled ? chalk.green("✓") : chalk.red("✗"),
+      r.fromWebstore ? chalk.green("✓") : chalk.dim("✗"),
+    ]);
+  }
+  console.log(table.toString());
+  printCount("extension(s)", results.length);
+});
+
+// ─── Search Engines Command ─────────────────────────────────────────────────
+
+const searchEnginesCmd = program.command("search-engines").description("List configured search engines");
+addCommonOptions(searchEnginesCmd).action((opts, cmd) => {
+  const mergedOpts = cmd.optsWithGlobals();
+  const results = getSearchEngines({
+    chromeDir: mergedOpts.chromeDir,
+    profile: mergedOpts.profile,
+  });
+
+  if (mergedOpts.json) return outputJSON(results);
+
+  if (results.length === 0) {
+    return printCount("search engines", 0);
+  }
+
+  console.log(chalk.bold("\n🔎 Search Engines:\n"));
+  const table = makeTable(["Name", "Keyword", "URL", "Active"], [20, 16, 60, 8]);
+  for (const r of results) {
+    table.push([
+      chalk.white(r.name),
+      chalk.cyan(r.keyword),
+      chalk.dim(r.url ? r.url.substring(0, 80) : "—"),
+      r.isActive ? chalk.green("✓") : chalk.dim("✗"),
+    ]);
+  }
+  console.log(table.toString());
+  printCount("search engine(s)", results.length);
+});
+
+// ─── Top Sites Command ──────────────────────────────────────────────────────
+
+const topSitesCmd = program.command("top-sites").description("List top sites");
+addCommonOptions(topSitesCmd).action((opts, cmd) => {
+  const mergedOpts = cmd.optsWithGlobals();
+  const results = getTopSites({
+    chromeDir: mergedOpts.chromeDir,
+    profile: mergedOpts.profile,
+  });
+
+  if (mergedOpts.json) return outputJSON(results);
+
+  if (results.length === 0) {
+    return printCount("top sites", 0);
+  }
+
+  console.log(chalk.bold("\n⭐ Top Sites:\n"));
+  const table = makeTable(["Rank", "Title", "URL"], [8, 30, 80]);
+  for (const r of results) {
+    table.push([
+      chalk.yellow(String(r.rank + 1)),
+      chalk.white(r.title || "—"),
+      chalk.cyan(r.url),
+    ]);
+  }
+  console.log(table.toString());
+  printCount("top site(s)", results.length);
+});
+
+// ─── 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]}`;
+}
+
+// ─── Run ─────────────────────────────────────────────────────────────────────
+
+program.parse();

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "chrome-tools",
+  "version": "1.0.1",
+  "description": "CLI & Node.js library to extract Chrome browser data (bookmarks, history, cookies, autofill, extensions, and more) on macOS",
+  "type": "module",
+  "main": "./src/index.js",
+  "exports": {
+    ".": "./src/index.js",
+    "./passwords": "./src/modules/passwords.js",
+    "./bookmarks": "./src/modules/bookmarks.js",
+    "./history": "./src/modules/history.js",
+    "./cookies": "./src/modules/cookies.js",
+    "./autofill": "./src/modules/autofill.js",
+    "./downloads": "./src/modules/downloads.js",
+    "./extensions": "./src/modules/extensions.js",
+    "./search-engines": "./src/modules/search-engines.js",
+    "./top-sites": "./src/modules/top-sites.js"
+  },
+  "bin": {
+    "chrome-tools": "./bin/cli.js"
+  },
+  "files": [
+    "bin",
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "start": "node bin/cli.js",
+    "test": "node bin/cli.js --help",
+    "release": "npm version patch --no-git-tag-version && npm publish"
+  },
+  "keywords": [
+    "chrome",
+    "bookmarks",
+    "history",
+    "cookies",
+    "autofill",
+    "browser",
+    "macos",
+    "keychain",
+    "cli"
+  ],
+  "author": "",
+  "license": "MIT",
+  "dependencies": {
+    "better-sqlite3": "^12.10.0",
+    "chalk": "^5.6.2",
+    "cli-table3": "^0.6.5",
+    "commander": "^13.0.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}