@ariesfish/feedloom 0.1.3 → 0.1.4

package/README.md

@@ -1,5 +1,15 @@
 # Feedloom
 
+<div align="center">
+  <img src="assets/logo.png" alt="Feedloom logo" width="160">
+  <p><strong>Archive long-form web content as clean Markdown with local assets.</strong></p>
+  <p>
+    <a href="https://www.npmjs.com/package/@ariesfish/feedloom"><img alt="npm" src="https://img.shields.io/npm/v/@ariesfish/feedloom"></a>
+    <img alt="Node.js >= 24" src="https://img.shields.io/badge/node-%3E%3D24-339933">
+    <img alt="License MIT" src="https://img.shields.io/badge/license-MIT-blue">
+  </p>
+</div>
+
 Feedloom is a command-line tool for archiving long-form web content. It takes article URLs, URL list files, or RSS/Atom feeds, extracts readable article content, converts it to Markdown with YAML frontmatter, and saves page images as local assets. It is designed for personal knowledge bases, notebook vaults, and offline reading archives.
 
 ## Features
@@ -43,6 +53,14 @@ If you plan to use `browser`, `stealth`, or the browser fallback in `auto` mode,
 npx patchright install chromium
 ```
 
+You can verify or repair the runtime later with:
+
+```bash
+npm run dev -- doctor
+```
+
+If the Patchright Chromium executable is missing, `doctor` runs `npx patchright install chromium` automatically.
+
 ### 4. Build the CLI
 
 ```bash
@@ -261,6 +279,12 @@ Only use this on your own device and accounts. Always respect the target site's
 --site-rules-dir <dir>          Optional directory of private TOML site rules
 ```
 
+Run environment checks:
+
+```bash
+npm run dev -- doctor
+```
+
 For the full option list, run:
 
 ```bash

package/dist/cli.js

@@ -2,6 +2,7 @@
 
 // src/cli.ts
 import { readdir as readdir2 } from "fs/promises";
+import { createRequire } from "module";
 import { dirname, join as join7, resolve as resolve2 } from "path";
 import { fileURLToPath } from "url";
 import { Command } from "commander";
@@ -112,11 +113,172 @@ function firstContentSelector(profiles) {
   return void 0;
 }
 
+// src/doctor.ts
+import { spawn } from "child_process";
+import { access } from "fs/promises";
+import { chromium } from "patchright";
+var INSTALL_CHROMIUM_COMMAND = "npx patchright install chromium";
+var INSTALL_CHROMIUM_HINT = `Run: ${INSTALL_CHROMIUM_COMMAND}`;
+function errorMessage(error) {
+  return error instanceof Error ? error.message : String(error);
+}
+function chromiumExecutablePath() {
+  const browserType = chromium;
+  return browserType.executablePath();
+}
+function appendCheck(checks, check) {
+  checks.push(check);
+}
+async function installPatchrightChromium(events = {}) {
+  return new Promise((resolve3, reject) => {
+    const child = spawn("npx", ["patchright", "install", "chromium"], {
+      stdio: ["ignore", "pipe", "pipe"]
+    });
+    child.stdout.setEncoding("utf8");
+    child.stderr.setEncoding("utf8");
+    child.stdout.on("data", (chunk) => events.onStdout?.(chunk));
+    child.stderr.on("data", (chunk) => events.onStderr?.(chunk));
+    child.on("error", reject);
+    child.on("close", (code, signal) => resolve3({ code, signal }));
+  });
+}
+async function executableExists(path) {
+  try {
+    await access(path);
+    return { ok: true };
+  } catch (error) {
+    return { ok: false, error };
+  }
+}
+async function ensureChromiumInstalled(checks, executablePath, options) {
+  const firstCheck = await executableExists(executablePath);
+  if (firstCheck.ok) {
+    appendCheck(checks, {
+      name: "Patchright Chromium installation",
+      ok: true,
+      message: "Chromium executable exists.",
+      detail: executablePath
+    });
+    return true;
+  }
+  appendCheck(checks, {
+    name: "Patchright Chromium installation",
+    ok: false,
+    message: "Chromium executable was not found on disk. Installing Patchright Chromium...",
+    detail: `${executablePath}
+${errorMessage(firstCheck.error)}`
+  });
+  let output = "";
+  const appendOutput = (chunk) => {
+    output += chunk;
+    options.stderr.write(chunk);
+  };
+  try {
+    const result = await options.installChromium({ onStdout: appendOutput, onStderr: appendOutput });
+    if (result.code !== 0) {
+      appendCheck(checks, {
+        name: "Patchright Chromium auto-install",
+        ok: false,
+        message: `Installation command failed with exit code ${result.code ?? "null"}${result.signal ? ` and signal ${result.signal}` : ""}.`,
+        detail: output.trim() || void 0,
+        hint: INSTALL_CHROMIUM_HINT
+      });
+      return false;
+    }
+  } catch (error) {
+    appendCheck(checks, {
+      name: "Patchright Chromium auto-install",
+      ok: false,
+      message: "Installation command failed to start or crashed.",
+      detail: errorMessage(error),
+      hint: INSTALL_CHROMIUM_HINT
+    });
+    return false;
+  }
+  const secondCheck = await executableExists(executablePath);
+  appendCheck(checks, secondCheck.ok ? {
+    name: "Patchright Chromium auto-install",
+    ok: true,
+    message: "Chromium installed successfully.",
+    detail: executablePath
+  } : {
+    name: "Patchright Chromium auto-install",
+    ok: false,
+    message: "Installation finished, but Chromium executable is still missing.",
+    detail: `${executablePath}
+${errorMessage(secondCheck.error)}`,
+    hint: INSTALL_CHROMIUM_HINT
+  });
+  return secondCheck.ok;
+}
+async function runDoctor(options = {}) {
+  const checks = [];
+  const resolvedOptions = {
+    installChromium: options.installChromium ?? installPatchrightChromium,
+    stderr: options.stderr ?? process.stderr
+  };
+  let executablePath = "";
+  try {
+    executablePath = chromiumExecutablePath();
+    checks.push({
+      name: "Patchright Chromium executable path",
+      ok: true,
+      message: executablePath
+    });
+  } catch (error) {
+    checks.push({
+      name: "Patchright Chromium executable path",
+      ok: false,
+      message: "Patchright does not report a Chromium executable for this platform.",
+      detail: errorMessage(error),
+      hint: INSTALL_CHROMIUM_HINT
+    });
+  }
+  const installed = executablePath ? await ensureChromiumInstalled(checks, executablePath, resolvedOptions) : false;
+  if (installed) {
+    try {
+      const browser = await chromium.launch({ headless: true });
+      await browser.close();
+      checks.push({
+        name: "Patchright Chromium launch",
+        ok: true,
+        message: "Chromium launched successfully in headless mode."
+      });
+    } catch (error) {
+      checks.push({
+        name: "Patchright Chromium launch",
+        ok: false,
+        message: "Chromium executable exists but failed to launch.",
+        detail: errorMessage(error),
+        hint: INSTALL_CHROMIUM_HINT
+      });
+    }
+  }
+  return {
+    ok: checks.at(-1)?.ok === true,
+    checks
+  };
+}
+function formatDoctorResult(result) {
+  const lines = ["Feedloom doctor"];
+  for (const check of result.checks) {
+    lines.push(`${check.ok ? "\u2713" : "\u2717"} ${check.name}: ${check.message}`);
+    if (check.detail) {
+      lines.push(...check.detail.split("\n").map((line) => `  ${line}`));
+    }
+    if (check.hint) {
+      lines.push(`  ${check.hint}`);
+    }
+  }
+  lines.push(result.ok ? "OK" : "FAILED");
+  return lines.join("\n");
+}
+
 // src/fetch/browser.ts
 import { mkdtemp, rm } from "fs/promises";
 import { tmpdir } from "os";
 import { join } from "path";
-import { chromium } from "patchright";
+import { chromium as chromium2 } from "patchright";
 var SCRAPLING_DEFAULT_ARGS = [
   "--no-pings",
   "--no-first-run",
@@ -165,7 +327,7 @@ async function launchBrowserContext(options) {
   if (options.dnsOverHttps) {
     extraArgs.push("--dns-over-https-templates=https://cloudflare-dns.com/dns-query");
   }
-  const context = await chromium.launchPersistentContext(userDataDir, {
+  const context = await chromium2.launchPersistentContext(userDataDir, {
     channel: options.channel,
     headless: options.headless ?? true,
     args: extraArgs,
@@ -242,7 +404,7 @@ async function fetchBrowserHtml(url, options = {}) {
 import { mkdtemp as mkdtemp2, rm as rm2 } from "fs/promises";
 import { tmpdir as tmpdir2 } from "os";
 import { join as join2 } from "path";
-import { chromium as chromium2 } from "patchright";
+import { chromium as chromium3 } from "patchright";
 var DEFAULT_ARGS = [
   "--no-pings",
   "--no-first-run",
@@ -385,7 +547,7 @@ async function solveCloudflare(page) {
 async function launchStealthContext(options) {
   const userDataDir = options.userDataDir ?? await mkdtemp2(join2(tmpdir2(), "feedloom-stealth-"));
   const ownsUserDataDir = options.userDataDir === void 0;
-  const context = await chromium2.launchPersistentContext(userDataDir, {
+  const context = await chromium3.launchPersistentContext(userDataDir, {
     channel: "chromium",
     headless: options.headless ?? true,
     args: stealthArgs(options),
@@ -1953,6 +2115,8 @@ var ProgressTracker = class {
 };
 
 // src/cli.ts
+var require2 = createRequire(import.meta.url);
+var packageJson = require2("../package.json");
 var program = new Command();
 async function siteRulePathsFromDir(dir) {
   const names = await readdir2(dir);
@@ -1968,7 +2132,13 @@ function positiveIntOption(value, fallback) {
   }
   return parsed;
 }
-program.name("feedloom").description("Archive long-form web content as clean Markdown with local assets").version("0.1.0").option("--output-dir <dir>", "Output directory for markdown notes", "clippings").option("--source-kind <kind>", "auto, html-page, or rss-feed", "auto").option("--since <date>", "Only keep feed entries on or after YYYY-MM-DD", "").option("--limit <n>", "Process only first N deduplicated URLs", "0").option("--start <n>", "Start from 1-based index after deduplication", "1").option("--end <n>", "End at 1-based index after deduplication", "0").option("--prefer-browser-state", "Try copied local Chrome profile before regular browser fallback", false).option("--chrome-user-data-dir <path>", "Chrome user data directory used with --prefer-browser-state", "").option("--chrome-profile <name>", "Chrome profile directory name", "Default").option("--fetch-mode <mode>", "auto, static, browser, or stealth", "auto").option("--no-network-idle", "Do not wait for browser networkidle before reading HTML").option("--wait-ms <ms>", "Extra browser wait after load", "2500").option("--solve-cloudflare", "In stealth mode, attempt Cloudflare Turnstile/interstitial challenge handling", false).option("--disable-resources", "In stealth mode, block images/media/fonts/stylesheets for speed", false).option("--proxy <server>", "Proxy server for browser/stealth fetch, e.g. http://127.0.0.1:8080", "").option("--dns-over-https", "Use Chromium Cloudflare DNS-over-HTTPS flag for browser/stealth fetch", false).option("--wait-selector <selector>", "Wait for a CSS selector after page load", "").option("--wait-selector-state <state>", "attached, detached, visible, or hidden", "attached").option("--click-selector <selector...>", "Click one or more selectors after page load", []).option("--scroll-to-bottom", "Scroll to the bottom before reading HTML", false).option("--headful", "Run browser/browser-state fetches with a visible Chrome window", false).option("--site-rules-dir <dir>", "Optional directory of private TOML site extraction/cleaning rules", "").option("--no-real-chrome-defaults", "Disable Scrapling-inspired real Chrome context defaults").option("--no-reuse-browser", "Disable batch browser/stealth context reuse").argument("[inputs...]", "URLs or files containing URLs").action(async (inputs, options) => {
+program.name("feedloom").description("Archive long-form web content as clean Markdown with local assets").version(packageJson.version ?? "0.0.0");
+program.command("doctor").description("Check Feedloom runtime dependencies").action(async () => {
+  const result = await runDoctor();
+  console.error(formatDoctorResult(result));
+  process.exitCode = result.ok ? 0 : 1;
+});
+program.option("--output-dir <dir>", "Output directory for markdown notes", "clippings").option("--source-kind <kind>", "auto, html-page, or rss-feed", "auto").option("--since <date>", "Only keep feed entries on or after YYYY-MM-DD", "").option("--limit <n>", "Process only first N deduplicated URLs", "0").option("--start <n>", "Start from 1-based index after deduplication", "1").option("--end <n>", "End at 1-based index after deduplication", "0").option("--prefer-browser-state", "Try copied local Chrome profile before regular browser fallback", false).option("--chrome-user-data-dir <path>", "Chrome user data directory used with --prefer-browser-state", "").option("--chrome-profile <name>", "Chrome profile directory name", "Default").option("--fetch-mode <mode>", "auto, static, browser, or stealth", "auto").option("--no-network-idle", "Do not wait for browser networkidle before reading HTML").option("--wait-ms <ms>", "Extra browser wait after load", "2500").option("--solve-cloudflare", "In stealth mode, attempt Cloudflare Turnstile/interstitial challenge handling", false).option("--disable-resources", "In stealth mode, block images/media/fonts/stylesheets for speed", false).option("--proxy <server>", "Proxy server for browser/stealth fetch, e.g. http://127.0.0.1:8080", "").option("--dns-over-https", "Use Chromium Cloudflare DNS-over-HTTPS flag for browser/stealth fetch", false).option("--wait-selector <selector>", "Wait for a CSS selector after page load", "").option("--wait-selector-state <state>", "attached, detached, visible, or hidden", "attached").option("--click-selector <selector...>", "Click one or more selectors after page load", []).option("--scroll-to-bottom", "Scroll to the bottom before reading HTML", false).option("--headful", "Run browser/browser-state fetches with a visible Chrome window", false).option("--site-rules-dir <dir>", "Optional directory of private TOML site extraction/cleaning rules", "").option("--no-real-chrome-defaults", "Disable Scrapling-inspired real Chrome context defaults").option("--no-reuse-browser", "Disable batch browser/stealth context reuse").argument("[inputs...]", "URLs or files containing URLs").action(async (inputs, options) => {
   if (inputs.length === 0) {
     program.help({ error: true });
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ariesfish/feedloom",
-  "version": "0.1.3",
+  "version": "0.1.4",
   "type": "module",
   "author": "ariesfish",
   "license": "MIT",
@@ -17,6 +17,7 @@
     "feedloom": "dist/cli.js"
   },
   "files": [
+    "assets",
     "dist",
     "skills",
     "README.md",

package/skills/feedloom/SKILL.md

@@ -22,6 +22,12 @@ npx -y @ariesfish/feedloom <inputs...> [options]
 
 ## Common usage
 
+Before clipping with browser-based fetch modes, run `doctor` once to verify and repair the Patchright Chromium runtime. If Chromium is missing, `doctor` automatically runs `npx patchright install chromium`.
+
+```bash
+npx -y @ariesfish/feedloom doctor
+```
+
 Before running Feedloom, check whether this skill directory has a `site-rules/` directory. If it exists, always pass it with `--site-rules-dir $HOME/.agents/skills/feedloom/site-rules`; do not omit available site rules.
 
 ```bash
@@ -61,7 +67,7 @@ Use the least expensive mode that works:
 - `--site-rules-dir <dir>`: load optional private TOML extraction/cleaning rules from a local directory, for example `$HOME/.agents/skills/feedloom/site-rules/` reference folder.
 - `--solve-cloudflare`, `--proxy <server>`, `--dns-over-https`: use only when stealth fetching needs them.
 
-Run `npx -y @ariesfish/feedloom --help` for the complete option list. Do not invent unsupported options.
+Run `npx -y @ariesfish/feedloom doctor` when browser, stealth, or auto fallback fails because Chromium is missing or cannot launch. Run `npx -y @ariesfish/feedloom --help` for the complete option list. Do not invent unsupported options.
 
 ## Site rules