@zeldrisho/pi-web-fetch 0.6.0 → 0.6.1

package/CHANGELOG.md

@@ -7,6 +7,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.6.1] - 2026-08-23
+
+### Fixed
+
+- Preserve the absolute URL when extracting HTML so Defuddle never constructs `new URL(pathname)` for GitHub-style host + path pages, and guard Defuddle failures (including detached rejections) so extraction always falls back to the basic converter instead of surfacing an `ERR_INVALID_URL` to the caller
+
 ## [0.6.0] - 2026-08-20
 
 ### Added
@@ -87,7 +93,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 - Add bounded public page fetching ([b979496](https://github.com/zeldrisho/pi-packages/commit/b979496b32de1cead172ba570307e4a4a7b3421d))
 
-[Unreleased]: https://github.com/zeldrisho/pi-packages/compare/pi-web-fetch-v0.6.0...HEAD
+[Unreleased]: https://github.com/zeldrisho/pi-packages/compare/pi-web-fetch-v0.6.1...HEAD
+[0.6.1]: https://github.com/zeldrisho/pi-packages/compare/pi-web-fetch-v0.6.0...pi-web-fetch-v0.6.1
 [0.6.0]: https://github.com/zeldrisho/pi-packages/compare/pi-web-fetch-v0.5.4...pi-web-fetch-v0.6.0
 [0.5.4]: https://github.com/zeldrisho/pi-packages/compare/pi-web-fetch-v0.5.3...pi-web-fetch-v0.5.4
 [0.5.3]: https://github.com/zeldrisho/pi-packages/compare/pi-web-fetch-v0.5.2...pi-web-fetch-v0.5.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zeldrisho/pi-web-fetch",
-  "version": "0.6.0",
+  "version": "0.6.1",
   "description": "Pi extension for secure, bounded public web page fetching and Markdown extraction",
   "keywords": [
     "pi",
@@ -35,10 +35,10 @@
     "linkedom": "^0.18.13"
   },
   "devDependencies": {
-    "@earendil-works/pi-coding-agent": "^0.84.0",
-    "@earendil-works/pi-tui": "^0.84.0",
-    "typebox": "^1.1.24",
-    "typescript": "^7.0.0",
+    "@earendil-works/pi-coding-agent": "^0.84.2",
+    "@earendil-works/pi-tui": "^0.84.2",
+    "typebox": "^1.3.16",
+    "typescript": "^7.0.2",
     "vite": "npm:@voidzero-dev/vite-plus-core@0.2.9",
     "vite-plus": "0.2.9"
   },

package/src/extract.ts

@@ -1,4 +1,5 @@
 import { parseHTML } from "linkedom";
+import type { DefuddleResponse } from "defuddle/node";
 
 const RAW_ID_SELECTOR_SAFE = /^-?[_a-zA-Z][-_a-zA-Z0-9]*$/;
 
@@ -75,11 +76,73 @@ export function htmlToMarkdownFallback(html: string): string {
     .trim();
 }
 
+/**
+ * Runs Defuddle over an already-normalized document with Markdown extraction enabled.
+ *
+ * Defuddle can fail in two distinct ways. The common case rejects the promise
+ * we `await` below, which the caller's `try/catch` catches and turns into a
+ * fallback. The dangerous case is when Defuddle schedules a throw on a
+ * *detached* microtask or timer — for example, when it resolves a
+ * document-relative link such as `/owner/repo/releases` into
+ * `new URL(relative, undefined)` *after* its own promise has already resolved.
+ * That rejection never reaches the `await` and instead escapes as an unhandled
+ * rejection that bypasses the surrounding `try/catch` and crashes the calling
+ * harness UI. Passing the absolute `pageUrl` prevents the URL-resolution form
+ * of this failure, but the guard below still covers any residual detached
+ * rejection.
+ *
+ * To keep `extractHtmlToMarkdown` from ever propagating such a failure, this
+ * helper arms a scoped `unhandledRejection` listener for the lifetime of the
+ * call. The listener is scoped, not process-wide in effect: it only treats a
+ * rejection as a Defuddle failure when its message or stack mentions Defuddle,
+ * so unrelated rejections from other concurrent work are ignored and do not
+ * force a spurious fallback to the basic extractor. After Defuddle resolves we
+ * flush a microtask and a macrotask so any rejection Defuddle scheduled settles
+ * inside the armed window; a rejection observed there is re-thrown so the
+ * caller falls back. Deeply-nested timers in Defuddle are out of scope and would
+ * still surface as a logged (non-crashing) unhandled rejection.
+ *
+ * @param document - The normalized document to parse
+ * @param pageUrl - The absolute URL of the page, used to resolve relative links
+ * @returns The Defuddle result, or `undefined` when extraction must fall back
+ */
+async function runDefuddle(
+  document: Document,
+  pageUrl: string,
+): Promise<DefuddleResponse | undefined> {
+  let escapedRejection: unknown = undefined;
+  let armed = true;
+  // Only attribute a rejection to Defuddle when it mentions Defuddle. This keeps
+  // the guard scoped so unrelated concurrent rejections are ignored.
+  const captureUnhandled = (cause: unknown): void => {
+    if (!armed || escapedRejection !== undefined) return;
+    const detail =
+      cause instanceof Error ? `${cause.message}\n${cause.stack ?? ""}` : String(cause);
+    if (/defuddle/i.test(detail)) escapedRejection = cause;
+  };
+  process.on("unhandledRejection", captureUnhandled);
+  try {
+    const { Defuddle } = await import("defuddle/node");
+    const result = await Defuddle(document, pageUrl, { markdown: true, useAsync: false });
+    // Let Defuddle's scheduled microtask/macrotask work settle so a detached
+    // rejection is observed by the guard instead of reaching the harness.
+    await Promise.resolve();
+    await new Promise<void>((resolve) => setImmediate(resolve));
+    if (escapedRejection !== undefined) throw escapedRejection;
+    return result;
+  } catch {
+    return undefined;
+  } finally {
+    armed = false;
+    process.off("unhandledRejection", captureUnhandled);
+  }
+}
+
 /**
  * Extracts readable Markdown and an optional title from HTML.
  *
  * @param html - The HTML document to convert
- * @param baseUrl - The base URL used to resolve document-relative links
+ * @param baseUrl - The absolute base URL used to resolve document-relative links
  * @returns The extracted Markdown, optional title, and extractor used
  */
 export async function extractHtmlToMarkdown(
@@ -87,16 +150,15 @@ export async function extractHtmlToMarkdown(
   baseUrl: URL,
 ): Promise<{ markdown: string; title?: string; extractor: "defuddle" | "basic" }> {
   try {
-    const { Defuddle } = await import("defuddle/node");
     const { document } = parseHTML(html);
     removeMalformedSchemaOrgData(document);
     normalizeSelectorUnsafeIds(document);
-    const result = await Defuddle(document, baseUrl.toString(), {
-      markdown: true,
-      useAsync: false,
-    });
-    const markdown = result.content?.trim() ?? "";
-    const trimmedTitle = result.title?.trim();
+    // Pass the full absolute URL so Defuddle resolves relative links (e.g.
+    // `/owner/repo/releases`) and metadata against the real origin instead of
+    // dropping the scheme and host and constructing `new URL(pathname)`.
+    const result = await runDefuddle(document, baseUrl.href);
+    const markdown = result?.content?.trim() ?? "";
+    const trimmedTitle = result?.title?.trim();
     if (markdown) {
       return {
         markdown,