digpile 1.0.0

package/README.md

@@ -0,0 +1,62 @@
+# digpile
+
+`digpile` is a small CLI that pulls one or more random bookmarks out of a bookmark folder so you can rediscover links you meant to revisit.
+
+It can read directly from:
+
+- Firefox profiles via `places.sqlite`
+- Chrome bookmarks
+- Brave bookmarks
+- Chromium bookmarks
+- Exported bookmarks HTML files
+
+## Requirements
+
+- Node.js `>=22`
+- macOS or Linux
+
+## Install
+
+```bash
+npm install -g digpile
+```
+
+For local development:
+
+```bash
+pnpm install
+pnpm build
+```
+
+## Usage
+
+Run against an installed browser profile:
+
+```bash
+digpile
+```
+
+Run against an exported bookmarks file:
+
+```bash
+digpile ~/bookmarks.html
+```
+
+Show help:
+
+```bash
+digpile --help
+```
+
+## Options
+
+- `-f, --folder <name>`: bookmark folder to search. Defaults to `Pile`.
+- `-n <number>`: number of bookmarks to surface. Defaults to `1`.
+
+## Examples
+
+```bash
+digpile
+digpile --folder "read later" -n 3
+digpile -f inbox -n 5 ~/bookmarks.html
+```

package/dist/constants.js

@@ -0,0 +1,51 @@
+export const DEFAULT_FOLDER = "Pile";
+export const BROWSERS = new Map([
+    [
+        "firefox",
+        {
+            name: "Firefox",
+            icon: "🦊",
+            type: "sqlite",
+            paths: {
+                darwin: "~/Library/Application Support/Firefox/Profiles",
+                linux: "~/.mozilla/firefox",
+            },
+        },
+    ],
+    [
+        "chrome",
+        {
+            name: "Chrome",
+            icon: "🌐",
+            type: "json",
+            paths: {
+                darwin: "~/Library/Application Support/Google/Chrome",
+                linux: "~/.config/google-chrome",
+            },
+        },
+    ],
+    [
+        "brave",
+        {
+            name: "Brave",
+            icon: "🦁",
+            type: "json",
+            paths: {
+                darwin: "~/Library/Application Support/BraveSoftware/Brave-Browser",
+                linux: "~/.config/BraveSoftware/Brave-Browser",
+            },
+        },
+    ],
+    [
+        "chromium",
+        {
+            name: "Chromium",
+            icon: "⚙️",
+            type: "json",
+            paths: {
+                darwin: "~/Library/Application Support/Chromium",
+                linux: "~/.config/chromium",
+            },
+        },
+    ],
+]);

package/dist/index.js

@@ -0,0 +1,57 @@
+#!/usr/bin/env node
+import fs from "node:fs";
+import chalk from "chalk";
+import { Command } from "@commander-js/extra-typings";
+import { intro, outro } from "@clack/prompts";
+import { DEFAULT_FOLDER } from "./constants.js";
+import { detectAvailableBrowsers } from "./utils/browser.js";
+import { printResult, readChromiumBookmarks, readFirefoxBookmarks, readHTMLBookmarks, } from "./utils/bookmark.js";
+import { promptBrowserAndProfile } from "./utils/prompt.js";
+import { fatal, getRandom } from "./utils/index.js";
+const program = new Command();
+program
+    .name("digpile")
+    .description("Dig a random link out of your bookmark pile")
+    .argument("[file]")
+    .option("-f, --folder <name>", "folder name to dig from", DEFAULT_FOLDER)
+    .option("-n <number>", "how many links to surface", (v) => parseInt(v, 10), 1)
+    .action(async (file, options) => {
+    intro(chalk.bold.green("⛏ digpile"));
+    let bookmarks;
+    if (file) {
+        if (!fs.existsSync(file)) {
+            return fatal(chalk.red(`File not found: ${file}`));
+        }
+        bookmarks = await readHTMLBookmarks(file, options.folder);
+        if (bookmarks.length === 0) {
+            return fatal(chalk.red(`Folder "${options.folder}" not found in ${file}.`) +
+                chalk.dim(" Try -f with a different folder name."));
+        }
+    }
+    else {
+        const available = detectAvailableBrowsers();
+        const { browser, profile } = await promptBrowserAndProfile(available);
+        if (browser.browser.type === "sqlite") {
+            bookmarks = await readFirefoxBookmarks(profile.path, options.folder);
+        }
+        else {
+            bookmarks = await readChromiumBookmarks(profile.path, options.folder);
+        }
+        if (bookmarks.length === 0) {
+            return fatal(chalk.red(`Folder "${options.folder}" not found.`) +
+                chalk.dim(" Try -f with a different folder name."));
+        }
+    }
+    const picks = getRandom(bookmarks, Math.max(1, options.n));
+    printResult(picks, bookmarks.length, options.folder);
+    outro("Happy browsing!");
+});
+program.addHelpText("after", `
+Examples:
+  digpile
+  digpile --folder "read later" -n 3
+  digpile -f inbox -n 5 ~/bookmarks.html
+
+Supported browsers:   Firefox 🦊  Chrome 🌐  Brave 🦁  Chromium ⚙️
+Supported platforms:  macOS · Linux`);
+program.parse();

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/dist/utils/bookmark.js

@@ -0,0 +1,108 @@
+import { box, log } from "@clack/prompts";
+import { readFile, copyFile, unlink } from "fs/promises";
+import chalk from "chalk";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import Database from "better-sqlite3";
+import { JSDOM } from "jsdom";
+import * as v from "valibot";
+export const readHTMLBookmarks = async (filePath, folderName) => {
+    const html = await readFile(filePath, "utf8");
+    const dom = new JSDOM(html);
+    const doc = dom.window.document;
+    const headers = Array.from(doc.querySelectorAll("h3"));
+    const targetHeader = headers.find((header) => header.textContent?.trim().toLowerCase() === folderName.toLowerCase());
+    const container = targetHeader?.nextElementSibling;
+    if (!container)
+        return [];
+    return Array.from(container.querySelectorAll("a")).map((anchor) => ({
+        title: anchor.textContent?.trim() || anchor.href,
+        url: anchor.href,
+    }));
+};
+export const readFirefoxBookmarks = async (dbPath, folderName) => {
+    const tmpPath = join(tmpdir(), `digpile-${Date.now()}.sqlite`);
+    await copyFile(dbPath, tmpPath);
+    try {
+        const db = new Database(tmpPath, { readonly: true });
+        const folderRows = db
+            .prepare("SELECT id FROM moz_bookmarks WHERE type = 2 AND LOWER(title) = LOWER(?)")
+            .all(folderName);
+        if (folderRows.length === 0) {
+            db.close();
+            return [];
+        }
+        const folderIds = folderRows.map((row) => row.id);
+        const placeholders = folderIds.map(() => "?").join(",");
+        const rows = db
+            .prepare(`WITH RECURSIVE subtree(id, type, fk, title) AS (
+          SELECT id, type, fk, title FROM moz_bookmarks
+          WHERE parent IN (${placeholders})
+          UNION ALL
+          SELECT b.id, b.type, b.fk, b.title
+          FROM moz_bookmarks b JOIN subtree s ON b.parent = s.id
+        )
+        SELECT s.title, p.url
+        FROM subtree s JOIN moz_places p ON s.fk = p.id
+        WHERE s.type = 1 AND p.url NOT LIKE 'place:%'`)
+            .all(...folderIds);
+        db.close();
+        return rows.map((row) => ({
+            title: row.title || row.url,
+            url: row.url,
+        }));
+    }
+    finally {
+        try {
+            await unlink(tmpPath);
+        }
+        catch { }
+    }
+};
+const ChromiumBookmarkNode = v.union([
+    v.object({
+        type: v.literal("folder"),
+        name: v.string(),
+        children: v.array(v.lazy(() => ChromiumBookmarkNode)),
+    }),
+    v.object({ type: v.literal("url"), name: v.string(), url: v.string() }),
+]);
+const ChromiumBookmarksFile = v.object({
+    roots: v.record(v.string(), ChromiumBookmarkNode),
+});
+export const readChromiumBookmarks = async (bookmarksPath, folderName) => {
+    const raw = await v.parseAsync(ChromiumBookmarksFile, JSON.parse(await readFile(bookmarksPath, "utf8")));
+    const bookmarks = [];
+    const collectAll = (node) => {
+        if (node.type === "url") {
+            bookmarks.push({ title: node.name, url: node.url });
+            return;
+        }
+        for (const child of node.children) {
+            collectAll(child);
+        }
+    };
+    const findFolder = (node) => {
+        if (node.type !== "folder")
+            return false;
+        if (node.name.toLowerCase() === folderName.toLowerCase()) {
+            collectAll(node);
+            return true;
+        }
+        return node.children.some(findFolder);
+    };
+    for (const root of Object.values(raw.roots)) {
+        if (findFolder(root))
+            break;
+    }
+    return bookmarks;
+};
+export const printResult = (bookmarks, total, folder) => {
+    box(bookmarks
+        .map((bookmark) => `${chalk.bold(bookmark.title)}\n${chalk.cyan(` ${bookmark.url}`)}`)
+        .join("\n\n"), "", {
+        rounded: true,
+        formatBorder: (text) => chalk.dim(text),
+    });
+    log.success(chalk.dim(`${bookmarks.length} of ${total} bookmarks surfaced from ` + chalk.italic(`"${folder}"`)));
+};

package/dist/utils/browser.js

@@ -0,0 +1,63 @@
+import fs from "node:fs";
+import { join } from "node:path";
+import { BROWSERS } from "../constants.js";
+import { expandHome } from "./index.js";
+import { detectPlatform } from "./platform.js";
+const findFirefoxProfiles = (basePath) => {
+    const dir = expandHome(basePath);
+    if (!fs.existsSync(dir))
+        return [];
+    return fs
+        .readdirSync(dir)
+        .filter((name) => {
+        try {
+            return (fs.statSync(join(dir, name)).isDirectory() &&
+                fs.existsSync(join(dir, name, "places.sqlite")));
+        }
+        catch {
+            return false;
+        }
+    })
+        .map((name) => ({
+        name,
+        path: join(dir, name, "places.sqlite"),
+    }));
+};
+const findChromiumProfiles = (basePath) => {
+    const dir = expandHome(basePath);
+    if (!fs.existsSync(dir))
+        return [];
+    const profiles = [];
+    const defaultBookmarksPath = join(dir, "Default", "Bookmarks");
+    if (fs.existsSync(defaultBookmarksPath)) {
+        profiles.push({ name: "Default", path: defaultBookmarksPath });
+    }
+    try {
+        fs.readdirSync(dir)
+            .filter((name) => /^Profile \d+$/.test(name))
+            .forEach((name) => {
+            const bookmarksPath = join(dir, name, "Bookmarks");
+            if (fs.existsSync(bookmarksPath)) {
+                profiles.push({ name, path: bookmarksPath });
+            }
+        });
+    }
+    catch { }
+    return profiles;
+};
+export const detectAvailableBrowsers = () => {
+    const platform = detectPlatform();
+    if (!platform)
+        return [];
+    const found = [];
+    for (const [key, browser] of BROWSERS) {
+        const basePath = browser.paths[platform];
+        if (!basePath)
+            continue;
+        const profiles = browser.type === "sqlite" ? findFirefoxProfiles(basePath) : findChromiumProfiles(basePath);
+        if (profiles.length > 0) {
+            found.push({ key, browser, profiles });
+        }
+    }
+    return found;
+};

package/dist/utils/index.js

@@ -0,0 +1,22 @@
+import { cancel } from "@clack/prompts";
+import { stat } from "node:fs/promises";
+import { homedir } from "node:os";
+export const expandHome = (path) => path.replace(/^~/, homedir());
+export const fatal = (message) => {
+    cancel(message);
+    process.exit(1);
+};
+export const nonFatal = (message) => {
+    cancel(message);
+    process.exit(0);
+};
+export const exists = async (f) => {
+    try {
+        await stat(f);
+        return true;
+    }
+    catch {
+        return false;
+    }
+};
+export const getRandom = (arr, n) => arr.toSorted(() => Math.random() - 0.5).slice(0, n);

package/dist/utils/platform.js

@@ -0,0 +1,7 @@
+export const detectPlatform = () => {
+    if (process.platform === "darwin")
+        return "darwin";
+    if (process.platform === "linux")
+        return "linux";
+    return null;
+};

package/dist/utils/prompt.js

@@ -0,0 +1,51 @@
+import chalk from "chalk";
+import { isCancel, log, select } from "@clack/prompts";
+import { fatal, nonFatal } from "./index.js";
+export const promptBrowserAndProfile = async (available) => {
+    if (available.length === 0) {
+        return fatal("No supported browsers found. Supported: Firefox, Chrome, Brave, Chromium.");
+    }
+    let selectedBrowser = available[0];
+    if (available.length === 1) {
+        log.info(chalk.dim(`Using ${selectedBrowser.browser.icon} ${selectedBrowser.browser.name}`));
+    }
+    else {
+        const key = await select({
+            message: "Browser",
+            options: available.map(({ browser, key }) => ({
+                label: `${browser.icon} ${browser.name}`,
+                value: key,
+            })),
+        });
+        if (isCancel(key)) {
+            return nonFatal("Operation cancelled");
+        }
+        const browser = available.find((entry) => entry.key === key);
+        if (!browser) {
+            return fatal(`Unknown browser selection: ${key}`);
+        }
+        selectedBrowser = browser;
+    }
+    let selectedProfile = selectedBrowser.profiles[0];
+    if (selectedBrowser.profiles.length === 1) {
+        log.info(chalk.dim(`Profile: ${selectedProfile.name}`));
+    }
+    else {
+        const profileName = await select({
+            message: "Profile",
+            options: selectedBrowser.profiles.map(({ name }) => ({
+                label: name,
+                value: name,
+            })),
+        });
+        if (isCancel(profileName)) {
+            return nonFatal("Operation cancelled");
+        }
+        const profile = selectedBrowser.profiles.find((entry) => entry.name === profileName);
+        if (!profile) {
+            return fatal(`Unknown profile selection: ${profileName}`);
+        }
+        selectedProfile = profile;
+    }
+    return { browser: selectedBrowser, profile: selectedProfile };
+};

package/package.json

@@ -0,0 +1,62 @@
+{
+  "name": "digpile",
+  "version": "1.0.0",
+  "description": "Dig a random link out of your bookmark pile",
+  "keywords": [
+    "bookmarks",
+    "chrome",
+    "cli",
+    "firefox",
+    "productivity",
+    "random"
+  ],
+  "homepage": "github:masiama/digpile",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/masiama/digpile.git"
+  },
+  "bin": {
+    "digpile": "dist/index.js"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "os": [
+    "darwin",
+    "linux"
+  ],
+  "type": "module",
+  "scripts": {
+    "build": "rm -rf ./dist && tsc -p tsconfig.build.json",
+    "prepack": "pnpm build",
+    "start": "node ./src/index.ts",
+    "start:dist": "node ./dist/index.js",
+    "lint": "oxlint",
+    "lint:fix": "oxlint --fix",
+    "fmt": "oxfmt",
+    "fmt:check": "oxfmt --check",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@clack/prompts": "^1.4.0",
+    "@commander-js/extra-typings": "^14.0.0",
+    "better-sqlite3": "12.10.0",
+    "chalk": "^5.6.2",
+    "commander": "^14.0.3",
+    "jsdom": "^29.1.1",
+    "valibot": "^1.4.0"
+  },
+  "devDependencies": {
+    "@types/better-sqlite3": "^7.6.13",
+    "@types/jsdom": "^28.0.3",
+    "@types/node": "^25.7.0",
+    "oxfmt": "^0.49.0",
+    "oxlint": "^1.64.0",
+    "typescript": "^6.0.3"
+  },
+  "engines": {
+    "node": ">=22"
+  }
+}