pi-quiver 4.1.1 → 4.3.0

package/CHANGELOG.md

@@ -8,6 +8,14 @@ Published to npm as `pi-quiver` (`pi install npm:pi-quiver`). Pushing a
 via OIDC trusted publishing. The release helper at
 `.agents/skills/release/scripts/release.sh` cuts the tag; CI publishes.
 
+## v4.3.0 - 2026-08-25
+
+- fetch: GitHub Actions job URLs (`.../actions/runs/<runId>/job/<jobId>`, singular `/job/` as GitHub's UI produces) now route through `gh run view --job <jobId> --repo <slug>`; plural `/jobs/<id>` paths still fall back to plain HTTP. Both run and job fetches now make a best-effort second `gh run view ... --log-failed` call and append its output under a `## Failed step logs` heading; when nothing failed, the run is still in progress, or logs have expired, the call yields no section and behavior is unchanged (summary-only).
+
+## v4.2.0 - 2026-08-20
+
+- fetch: data plane extracted to `lib/fetch-core.ts`; new `pi-quiver fetch` CLI (esbuild-built `dist/` bin) with full parameter parity; Claude Code skill + plugin marketplace (`quiver:fetch` via `npx -y pi-quiver@latest`). pi tool behavior unchanged.
+
 ## v4.1.1 - 2026-08-17
 
 - **`session-name`: fix silent auto-naming failure on GitHub Copilot business/enterprise accounts.** Those credentials pin requests to an account-specific endpoint (`auth.baseUrl` from `getApiKeyAndHeaders`); the naming call ignored it and hit the catalog's individual endpoint, failing with `421 Misdirected Request` and leaving sessions unnamed. The naming request now mirrors pi's own request path and prefers the credential's endpoint.

package/README.md

@@ -62,7 +62,7 @@ A 300 KB changelog page never touches your context window - you get a preview an
 
 | Extension | Tool | What it does |
 | --- | --- | --- |
-| `extensions/fetch.ts` | `fetch` | Retrieve URLs over HTTP(S). HTML -> Markdown (Readability extraction, Turndown conversion). Binary saved untouched to a temp file. GitHub issue/PR/repo/actions-run URLs auto-route through `gh` (falls back to HTTP). Same size gate as `doc_to_md`. |
+| `extensions/fetch.ts` | `fetch` | Retrieve URLs over HTTP(S). HTML -> Markdown (Readability extraction, Turndown conversion). Binary saved untouched to a temp file. GitHub issue/PR/repo/actions-run/actions-job URLs auto-route through `gh` (falls back to HTTP); failed runs/jobs include failed-step logs (best-effort, summary-only otherwise). Same size gate as `doc_to_md`. Behavior lives in `lib/fetch-core.ts`; also exposed as the `pi-quiver fetch` CLI (see [Claude Code support](#claude-code-support)). |
 | `extensions/doc_to_md.ts` | `doc_to_md` | Convert a local PDF/DOCX/PPTX to Markdown. High-fidelity via `pymupdf4llm` (run through `uv`); degraded pure-JS fallback (`unpdf`) when `uv`/Python is unavailable or conversion times out. DOCX/PPTX convert via LibreOffice first. |
 | `extensions/session-name.ts` | `/session-name` | Manual + opt-in automatic session naming, naming rules and deny list, long-session revisits, and Ghostty tab rename. OFF by default. |
 | `extensions/sword-header.ts` | `/builtin-header` | Themed ASCII startup header replacing pi's default logo. OFF by default. |
@@ -76,7 +76,7 @@ Full routing rules, size-gate mechanics, and config: [doc/fetch.md](doc/fetch.md
 | Concept | Meaning |
 | --- | --- |
 | Size gate | Text/Markdown/JSON output over 32 KB or 1000 lines spills to a temp file with a 60-line preview instead of inlining. |
-| Content routing | HTML -> Markdown, binary -> untouched file, GitHub URLs -> `gh` CLI, everything else -> the size gate. |
+| Content routing | HTML -> Markdown, binary -> untouched file, GitHub URLs -> `gh` CLI (failed runs/jobs get failed-step logs appended), everything else -> the size gate. |
 | Graceful degradation | Optional binaries (`gh`, `uv`, LibreOffice) are never hard install-time deps; each has a defined, documented fallback or failure mode. |
 | Opt-in extensions | `session-name`, `sword-header`, `fast-mode`, and `provider-stall-watchdog` do nothing until explicitly enabled in `settings.json`. |
 | Provider stall recovery | The watchdog detects a missing first stream event and missing parsed semantic progress, not network liveness. The pre-first-event tier covers every mode and origin; the mid-stream tier is TUI-only. |
@@ -129,7 +129,7 @@ The npm package's bundled JS deps install automatically on `pi install`. A few *
 
 | Prerequisite | Needed by | If absent |
 | --- | --- | --- |
-| `gh` (GitHub CLI, installed + `gh auth login`) | `fetch` GitHub issue/PR/repo/actions-run routing | Falls back to an HTTP fetch of the rendered page (private repos hit a login wall). |
+| `gh` (GitHub CLI, installed + `gh auth login`) | `fetch` GitHub issue/PR/repo/actions-run/actions-job routing | Falls back to an HTTP fetch of the rendered page (private repos hit a login wall). |
 | `uv` (+ managed Python 3.14, fetched on first use) | `doc_to_md` high-fidelity PDF conversion | Degrades to the pure-JS `unpdf` fallback (no faithful tables/headings). |
 | LibreOffice (`soffice` on `PATH`) | `doc_to_md` DOCX/PPTX conversion | Office inputs error (no JS fallback for office->PDF); PDFs unaffected. |
 
@@ -205,6 +205,29 @@ Operational notes:
 - **A watchdog abort that the provider ignores escalates after a fixed 10s.** Any post-abort stream event re-arms that deadline (bytes prove only that the connection was alive at that instant), so a stream that emits a straggler and then wedges still escalates 10s after its last event. This reduces the hang; it cannot force the provider to stop, and undici's timeouts remain the final backstop.
 - **Headless runs report on stderr.** In `print`/`json` mode pi binds a no-op UI, so watchdog notices go out via `console.warn`. Nothing is ever written to stdout, which `json` mode uses for its protocol. In TUI and RPC the notices render as main-window notifications, not the bottom status line.
 
+## Claude Code support
+
+`fetch`'s core (`lib/fetch-core.ts`) is also published as a CLI, so Claude Code can use the same routing, size gate, and spill behavior as pi's native tool - without pi ever seeing Claude-only files.
+
+**Exposed:** the `quiver` plugin, served from this repo's `.claude-plugin/marketplace.json`, with one skill: `fetch` (invoked as `quiver:fetch` / `/quiver:fetch`). The skill runs `npx -y pi-quiver@latest fetch <url> [flags]` via Bash - full parameter parity with the pi tool (`--method`, `--header`, `--body`, `--raw`, `--timeout-ms`), same GitHub `gh` routing (including failed-step logs on failed runs/jobs), same size gate, same binary-to-temp-file handling. See [doc/fetch.md](doc/fetch.md#claude-code-cli-pi-quiver-fetch) for exit codes and flags.
+
+**Not exposed:** pi extensions, `doc_to_md`, and everything else in this package - the marketplace allowlists only `./skills/fetch`, and the npm tarball never ships `skills/` or `.claude-plugin/` (pi's own `files` allowlist excludes them, and pi's explicit `pi.extensions` manifest makes them invisible to pi's convention-directory auto-discovery either way).
+
+Add the marketplace and enable the plugin in `.claude/settings.json`:
+
+```json
+{
+	"extraKnownMarketplaces": {
+		"pi-quiver": { "source": { "source": "github", "repo": "jjuraszek/pi-quiver" } }
+	},
+	"enabledPlugins": { "quiver@pi-quiver": true }
+}
+```
+
+Activates on folder trust.
+
+**Release sequencing:** the skill goes live only with (or after) the npm release that ships the `pi-quiver` bin - until that tag is on npm, `npx -y pi-quiver@latest fetch` resolves a bin-less package and fails.
+
 ## Development
 
 Deps are peers (`@earendil-works/*`, `@sinclair/typebox`) plus the bundled
@@ -222,6 +245,10 @@ Both run in CI on ubuntu + windows (`.github/workflows/test.yml`).
 
 pi-quiver is how ground truth gets into an agent's context - real pages, PDFs, docs, cleanly and safely. The other three then coordinate work over it ([pi-cohort](https://github.com/jjuraszek/pi-cohort)), prune it once it's stale ([pi-condense](https://github.com/jjuraszek/pi-condense)), and govern the process end to end ([pi-gauntlet](https://github.com/jjuraszek/pi-gauntlet)).
 
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) - issues follow a Context / Problem / Idea / Acceptance Criteria template; PRs run the [pi-gauntlet](https://github.com/jjuraszek/pi-gauntlet) workflow (one-liners exempt from ceremony, never from keeping docs truthful).
+
 ## Support
 
 If this saves you time, consider [buying me a coffee](https://buymeacoffee.com/jjurasszek).

package/dist/bin/pi-quiver.js

@@ -0,0 +1,604 @@
+#!/usr/bin/env node
+
+// bin/pi-quiver.ts
+import { realpathSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { resolve } from "node:path";
+
+// lib/fetch-core.ts
+import { mkdirSync, writeFileSync, createWriteStream } from "node:fs";
+import { rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { createHash } from "node:crypto";
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { JSDOM } from "jsdom";
+import { Readability } from "@mozilla/readability";
+import TurndownService from "turndown";
+import { gfm } from "turndown-plugin-gfm";
+function formatSize(bytes) {
+  if (bytes < 1024) {
+    return `${bytes}B`;
+  } else if (bytes < 1024 * 1024) {
+    return `${(bytes / 1024).toFixed(1)}KB`;
+  } else {
+    return `${(bytes / (1024 * 1024)).toFixed(1)}MB`;
+  }
+}
+var RESERVED_OWNERS = /* @__PURE__ */ new Set([
+  "orgs",
+  "users",
+  "sponsors",
+  "topics",
+  "marketplace",
+  "apps",
+  "collections",
+  "stars",
+  "settings",
+  "notifications",
+  "codespaces",
+  "features",
+  "trending",
+  "security",
+  "customer-stories"
+]);
+var GH_NAME = /^[A-Za-z0-9._-]+$/;
+function classifyGitHubTarget(url) {
+  const host = url.hostname.toLowerCase();
+  if (host !== "github.com" && host !== "www.github.com") return null;
+  const segs = url.pathname.split("/").filter((s) => s.length > 0);
+  if (segs.length < 2) return null;
+  const [owner, repo] = segs;
+  if (!GH_NAME.test(owner) || !GH_NAME.test(repo)) return null;
+  if (RESERVED_OWNERS.has(owner.toLowerCase())) return null;
+  if (segs.length === 4 && segs[2] === "issues" && /^\d+$/.test(segs[3])) {
+    return { kind: "issue", url: `https://github.com/${owner}/${repo}/issues/${segs[3]}` };
+  }
+  if (segs.length === 4 && segs[2] === "pull" && /^\d+$/.test(segs[3])) {
+    return { kind: "pr", url: `https://github.com/${owner}/${repo}/pull/${segs[3]}` };
+  }
+  if (segs.length === 5 && segs[2] === "actions" && segs[3] === "runs" && /^\d+$/.test(segs[4])) {
+    return { kind: "run", slug: `${owner}/${repo}`, runId: segs[4], url: `https://github.com/${owner}/${repo}/actions/runs/${segs[4]}` };
+  }
+  if (segs.length === 7 && segs[2] === "actions" && segs[3] === "runs" && /^\d+$/.test(segs[4]) && segs[5] === "job" && /^\d+$/.test(segs[6])) {
+    return { kind: "job", slug: `${owner}/${repo}`, jobId: segs[6], url: `https://github.com/${owner}/${repo}/actions/runs/${segs[4]}/job/${segs[6]}` };
+  }
+  if (segs.length === 2) {
+    return { kind: "repo", slug: `${owner}/${repo}` };
+  }
+  return null;
+}
+function buildGhArgs(target) {
+  if (target.kind === "issue") return ["issue", "view", target.url, "--comments"];
+  if (target.kind === "pr") return ["pr", "view", target.url, "--comments"];
+  if (target.kind === "run") return ["run", "view", target.runId, "--repo", target.slug];
+  if (target.kind === "job") return ["run", "view", "--job", target.jobId, "--repo", target.slug];
+  return ["repo", "view", target.slug];
+}
+function buildGhLogArgs(target) {
+  if (target.kind === "run") return ["run", "view", target.runId, "--log-failed", "--repo", target.slug];
+  if (target.kind === "job") return ["run", "view", "--job", target.jobId, "--log-failed", "--repo", target.slug];
+  return null;
+}
+var GH_MAX_BUFFER = 1e7;
+var execFileAsync = promisify(execFile);
+var runGh = async (args, timeoutMs, signal) => {
+  try {
+    const { stdout } = await execFileAsync("gh", args, {
+      timeout: timeoutMs,
+      signal,
+      maxBuffer: GH_MAX_BUFFER,
+      encoding: "utf8"
+    });
+    if (!stdout.trim()) return { ok: false };
+    return { ok: true, stdout };
+  } catch {
+    return { ok: false };
+  }
+};
+function planGhRouting(params, url) {
+  if (params.raw) return null;
+  if ((params.method ?? "GET") !== "GET") return null;
+  if (params.body) return null;
+  if (params.headers && Object.keys(params.headers).length > 0) return null;
+  return classifyGitHubTarget(url);
+}
+function ghCommandLabel(target) {
+  if (target.kind === "issue") return "issue view --comments";
+  if (target.kind === "pr") return "pr view --comments";
+  if (target.kind === "run") return "run view";
+  if (target.kind === "job") return "run view --job";
+  return "repo view";
+}
+function ghSourceLine(target, ref) {
+  if (target.kind === "issue") return `gh issue view ${ref} --comments`;
+  if (target.kind === "pr") return `gh pr view ${ref} --comments`;
+  if (target.kind === "run") return `gh run view ${target.runId} --repo ${target.slug}`;
+  if (target.kind === "job") return `gh run view --job ${target.jobId} --repo ${target.slug}`;
+  return `gh repo view ${ref}`;
+}
+function renderGhResult(target, stdout, failedLogs) {
+  const body = failedLogs !== void 0 ? `${stdout.trimEnd()}
+
+## Failed step logs
+
+${failedLogs.trimEnd()}` : stdout.trimEnd();
+  const ref = target.kind === "repo" ? target.slug : target.url;
+  const { spill, bytes, lines } = applyGate(body);
+  const baseDetails = {
+    url: ref,
+    bytes,
+    lines,
+    category: "markdown",
+    via: "gh",
+    ghCommand: ghCommandLabel(target)
+  };
+  const source = failedLogs !== void 0 ? `Source: ${ghSourceLine(target, ref)}
+Source: gh ${buildGhLogArgs(target).join(" ")}` : `Source: ${ghSourceLine(target, ref)}`;
+  if (!spill) {
+    return {
+      output: [source, "", body].join("\n"),
+      details: { ...baseDetails, spilled: false }
+    };
+  }
+  const spillUrl = target.kind === "repo" ? `https://github.com/${target.slug}` : target.url;
+  const file = spillToFile(spillUrl, body, "md");
+  return {
+    output: [
+      source,
+      `Body: ${formatSize(bytes)} across ${lines} lines \u2014 written to file (too large to inline)`,
+      `Saved-To: ${file}`,
+      "",
+      "Read slices of this file with the read tool (offset/limit) or grep it; do not read the whole file unless you must. Markdown is grep-able by heading (^#).",
+      "",
+      `----- preview (first ${PREVIEW_LINES} lines) -----`,
+      buildPreview(body)
+    ].join("\n"),
+    details: { ...baseDetails, spilled: true, file }
+  };
+}
+async function executeGhRouting(params, url, signal, runner = runGh) {
+  const target = planGhRouting(params, url);
+  if (!target) return null;
+  const timeoutMs = params.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+  signal?.throwIfAborted();
+  const gh = await runner(buildGhArgs(target), timeoutMs, signal);
+  signal?.throwIfAborted();
+  if (!gh.ok) return null;
+  const logArgs = buildGhLogArgs(target);
+  let failedLogs;
+  if (logArgs) {
+    const logs = await runner(logArgs, timeoutMs, signal);
+    signal?.throwIfAborted();
+    if (logs.ok && logs.stdout !== "") failedLogs = logs.stdout;
+  }
+  return renderGhResult(target, gh.stdout, failedLogs);
+}
+var PARSABLE_MAX_BYTES = 1e6;
+var BINARY_MAX_BYTES = 5e7;
+var SNIFF_MAX_BYTES = 64e3;
+var DEFAULT_TIMEOUT_MS = 2e4;
+var INLINE_MAX_BYTES = 32e3;
+var INLINE_MAX_LINES = 1e3;
+var PREVIEW_LINES = 60;
+var PREVIEW_MAX_BYTES = 4e3;
+var FIREFOX_UA = "Mozilla/5.0 (Macintosh; Intel Mac OS X 14.7; rv:135.0) Gecko/20100101 Firefox/135.0";
+var DEFAULT_ACCEPT = "text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8";
+function parseCharset(contentType) {
+  const m = /charset\s*=\s*"?([^";\s]+)"?/i.exec(contentType);
+  return (m?.[1] ?? "utf-8").trim().toLowerCase();
+}
+function decodeBuffer(buf, charset) {
+  try {
+    return new TextDecoder(charset, { fatal: false }).decode(buf);
+  } catch {
+    return new TextDecoder("utf-8", { fatal: false }).decode(buf);
+  }
+}
+function buildPreview(body) {
+  let preview = body.split("\n").slice(0, PREVIEW_LINES).join("\n");
+  if (preview.length > PREVIEW_MAX_BYTES) {
+    preview = `${preview.slice(0, PREVIEW_MAX_BYTES)}
+\u2026[preview truncated]`;
+  }
+  return preview;
+}
+var turndownService = new TurndownService({
+  headingStyle: "atx",
+  codeBlockStyle: "fenced",
+  bulletListMarker: "-"
+});
+turndownService.use(gfm);
+function mimeType(contentType) {
+  return contentType.split(";")[0].trim().toLowerCase();
+}
+var TEXT_ALLOWLIST = [
+  /^text\//,
+  /^application\/(json|xml|xhtml\+xml|javascript)$/,
+  /\+json$/,
+  /\+xml$/
+];
+var KNOWN_BINARY = [
+  /^audio\//,
+  /^video\//,
+  /^font\//,
+  /^application\/(pdf|zip|gzip|x-tar|x-7z-compressed|x-rar-compressed|wasm)$/
+];
+function categorize(contentType, sniff, raw) {
+  const mime = mimeType(contentType);
+  if (/^image\//.test(mime)) return "binary";
+  const isText = TEXT_ALLOWLIST.some((re) => re.test(mime));
+  const isBinary = KNOWN_BINARY.some((re) => re.test(mime));
+  if (!isText && !isBinary) return sniff.includes(0) ? "binary" : "text";
+  if (isBinary && !isText) return "binary";
+  if (sniff.includes(0)) return "binary";
+  if (raw) return "text";
+  if (mime === "text/html" || mime === "application/xhtml+xml") return "markdown";
+  if (mime === "application/json" || /\+json$/.test(mime)) return "json";
+  return "text";
+}
+function htmlToMarkdown(html, url) {
+  let doc;
+  try {
+    doc = new JSDOM(html, { url }).window.document;
+  } catch {
+    return null;
+  }
+  let article = null;
+  try {
+    article = new Readability(doc).parse();
+  } catch {
+    return null;
+  }
+  if (!article?.content) return null;
+  let md;
+  try {
+    md = turndownService.turndown(article.content).trim();
+  } catch {
+    return null;
+  }
+  if (!md) return null;
+  if (article.title) md = `# ${article.title}
+
+${md}`;
+  return md;
+}
+function prettyJson(text) {
+  try {
+    return JSON.stringify(JSON.parse(text), null, 2);
+  } catch {
+    return text;
+  }
+}
+function applyGate(body) {
+  const bytes = Buffer.byteLength(body, "utf8");
+  const lines = body.length ? body.split("\n").length : 0;
+  const spill = body.length > 0 && (bytes > INLINE_MAX_BYTES || lines > INLINE_MAX_LINES);
+  return { spill, bytes, lines };
+}
+function tempFilePath(url, ext) {
+  const dir = join(tmpdir(), "pi-fetch");
+  mkdirSync(dir, { recursive: true });
+  let host = "page";
+  try {
+    host = new URL(url).hostname.replace(/[^a-z0-9.-]/gi, "_") || "page";
+  } catch {
+  }
+  const hash = createHash("sha1").update(url).digest("hex").slice(0, 8);
+  const stamp = (/* @__PURE__ */ new Date()).toISOString().replace(/[:.]/g, "-");
+  return join(dir, `${stamp}-${host}-${hash}.${ext}`);
+}
+function spillToFile(url, body, ext) {
+  const file = tempFilePath(url, ext);
+  writeFileSync(file, body, "utf8");
+  return file;
+}
+function textExtension(category, contentType) {
+  if (category === "markdown") return "md";
+  if (category === "json") return "json";
+  return mimeType(contentType).includes("xml") ? "xml" : "txt";
+}
+var BINARY_EXT = {
+  "application/pdf": "pdf",
+  "application/zip": "zip",
+  "application/vnd.openxmlformats-officedocument.wordprocessingml.document": "docx",
+  "application/vnd.openxmlformats-officedocument.presentationml.presentation": "pptx",
+  "application/gzip": "gz",
+  "image/png": "png",
+  "image/jpeg": "jpg",
+  "image/gif": "gif",
+  "image/webp": "webp",
+  "image/svg+xml": "svg"
+};
+function binaryExtension(contentType) {
+  const mime = mimeType(contentType);
+  if (BINARY_EXT[mime]) return BINARY_EXT[mime];
+  const sub = (mime.split("/")[1] ?? "").replace(/^x-/, "").replace(/[^a-z0-9]+/g, "").slice(0, 8);
+  return sub || "bin";
+}
+function writeChunk(stream, b) {
+  return new Promise((resolve2, reject) => {
+    stream.write(b, (err) => err ? reject(err) : resolve2());
+  });
+}
+async function pumpToFile(stream, reader, prefix, exhausted) {
+  let bytes = 0;
+  let truncated = false;
+  let head = prefix;
+  if (head.length > BINARY_MAX_BYTES) {
+    head = head.subarray(0, BINARY_MAX_BYTES);
+    truncated = true;
+  }
+  await writeChunk(stream, head);
+  bytes += head.length;
+  while (!exhausted && !truncated) {
+    const { done, value } = await reader.read();
+    if (done) break;
+    let chunk = Buffer.from(value);
+    if (bytes + chunk.length > BINARY_MAX_BYTES) {
+      chunk = chunk.subarray(0, BINARY_MAX_BYTES - bytes);
+      truncated = true;
+    }
+    await writeChunk(stream, chunk);
+    bytes += chunk.length;
+  }
+  await new Promise((resolve2, reject) => stream.end((err) => err ? reject(err) : resolve2()));
+  return { bytes, truncated };
+}
+async function collectBody(res, contentType, raw) {
+  const reader = res.body.getReader();
+  const prefixParts = [];
+  let prefixLen = 0;
+  let exhausted = false;
+  while (prefixLen < SNIFF_MAX_BYTES) {
+    const { done, value } = await reader.read();
+    if (done) {
+      exhausted = true;
+      break;
+    }
+    const chunk = Buffer.from(value);
+    prefixParts.push(chunk);
+    prefixLen += chunk.length;
+  }
+  const prefix = Buffer.concat(prefixParts);
+  const category = categorize(contentType, prefix.subarray(0, SNIFF_MAX_BYTES), raw);
+  if (category === "binary") {
+    const file = tempFilePath(res.url, binaryExtension(contentType));
+    const stream = createWriteStream(file);
+    try {
+      const { bytes: bytes2, truncated: truncated2 } = await pumpToFile(stream, reader, prefix, exhausted);
+      if (truncated2) await reader.cancel().catch(() => {
+      });
+      return { category, file, bytes: bytes2, truncated: truncated2 };
+    } catch (err) {
+      stream.destroy();
+      await rm(file, { force: true });
+      await reader.cancel().catch(() => {
+      });
+      throw err;
+    }
+  }
+  const parts = [prefix];
+  let bytes = prefix.length;
+  let streamDone = exhausted;
+  while (!streamDone && bytes < PARSABLE_MAX_BYTES) {
+    const { done, value } = await reader.read();
+    if (done) {
+      streamDone = true;
+      break;
+    }
+    const chunk = Buffer.from(value);
+    parts.push(chunk);
+    bytes += chunk.length;
+  }
+  let buffer = Buffer.concat(parts);
+  if (buffer.length > PARSABLE_MAX_BYTES) {
+    buffer = buffer.subarray(0, PARSABLE_MAX_BYTES);
+  }
+  const truncated = !streamDone;
+  if (truncated) await reader.cancel().catch(() => {
+  });
+  return { category, buffer, bytes: buffer.length, truncated };
+}
+async function fetchUrl(opts) {
+  const url = new URL(opts.url);
+  if (url.protocol !== "http:" && url.protocol !== "https:") {
+    throw new Error(`Unsupported protocol: ${url.protocol}`);
+  }
+  const ghResult = await executeGhRouting(opts, url, opts.signal);
+  if (ghResult) return ghResult;
+  const headers = new Headers(opts.headers ?? {});
+  if (!headers.has("user-agent")) headers.set("user-agent", FIREFOX_UA);
+  if (!headers.has("accept")) headers.set("accept", DEFAULT_ACCEPT);
+  if (!headers.has("accept-language"))
+    headers.set("accept-language", "en-US,en;q=0.5");
+  const controller = new AbortController();
+  const onAbort = () => controller.abort();
+  opts.signal?.addEventListener("abort", onAbort);
+  const timer = setTimeout(
+    () => controller.abort(new Error("fetch timeout")),
+    opts.timeoutMs ?? DEFAULT_TIMEOUT_MS
+  );
+  try {
+    const res = await fetch(url, {
+      method: opts.method ?? "GET",
+      headers,
+      body: opts.body,
+      signal: controller.signal,
+      redirect: "follow"
+    });
+    const ct = res.headers.get("content-type") ?? "";
+    const charset = parseCharset(ct);
+    const header = [
+      `HTTP ${res.status} ${res.statusText}`,
+      `Content-Type: ${ct}`,
+      `Charset: ${charset}`
+    ];
+    if (!res.body || (opts.method ?? "GET") === "HEAD") {
+      return {
+        output: [...header, "Length: 0 (no body)"].join("\n"),
+        details: { url: res.url, status: res.status, contentType: ct, charset, bytes: 0 }
+      };
+    }
+    const collected = await collectBody(res, ct, opts.raw ?? false);
+    const baseDetails = {
+      url: res.url,
+      status: res.status,
+      contentType: ct,
+      charset,
+      bytes: collected.bytes,
+      truncated: collected.truncated,
+      category: collected.category
+    };
+    if (collected.category === "binary") {
+      const note = collected.truncated ? " (truncated to 50MB)" : "";
+      return {
+        output: [
+          ...header,
+          `Body: ${formatSize(collected.bytes)}${note} binary (${mimeType(ct) || "unknown"}) \u2014 saved untouched for processing`,
+          `Saved-To: ${collected.file}`,
+          "",
+          "Binary content is not decoded. Use the appropriate tool to process the file at the path above."
+        ].join("\n"),
+        details: { ...baseDetails, spilled: true, file: collected.file }
+      };
+    }
+    const decoded = decodeBuffer(collected.buffer, charset);
+    let body;
+    let effectiveCategory = collected.category;
+    if (collected.category === "markdown") {
+      const md = htmlToMarkdown(decoded, res.url);
+      if (md !== null) {
+        body = md;
+      } else {
+        body = decoded;
+        effectiveCategory = "text";
+      }
+    } else if (collected.category === "json") {
+      body = prettyJson(decoded);
+    } else {
+      body = decoded;
+    }
+    baseDetails.category = effectiveCategory;
+    const truncNote = collected.truncated ? "\n[Note: source truncated at 1MB \u2014 content may be partial]" : "";
+    const lengthLine = `Length: ${collected.bytes}${collected.truncated ? " (truncated to 1MB)" : ""}`;
+    const { spill, bytes: bodyBytes, lines: lineCount } = applyGate(body);
+    baseDetails.lines = lineCount;
+    if (!spill) {
+      return {
+        output: [...header, lengthLine, "", body + truncNote].join("\n"),
+        details: { ...baseDetails, spilled: false }
+      };
+    }
+    const ext = textExtension(effectiveCategory, ct);
+    const file = spillToFile(res.url, body, ext);
+    const grepHint = effectiveCategory === "markdown" ? "Read slices of this file with the read tool (offset/limit) or grep it; do not read the whole file unless you must. Markdown is grep-able by heading (^#)." : "Read slices of this file with the read tool (offset/limit) or grep it; do not read the whole file unless you must.";
+    return {
+      output: [
+        ...header,
+        lengthLine,
+        `Body: ${formatSize(bodyBytes)} across ${lineCount} lines \u2014 written to file (too large to inline)`,
+        `Saved-To: ${file}`,
+        ...collected.truncated ? ["[Note: source truncated at 1MB \u2014 content may be partial]"] : [],
+        "",
+        grepHint,
+        "",
+        `----- preview (first ${PREVIEW_LINES} lines) -----`,
+        buildPreview(body)
+      ].join("\n"),
+      details: { ...baseDetails, spilled: true, file }
+    };
+  } finally {
+    clearTimeout(timer);
+    opts.signal?.removeEventListener("abort", onAbort);
+  }
+}
+
+// bin/pi-quiver.ts
+var USAGE = 'Usage: pi-quiver fetch <url> [--method GET|HEAD|POST] [--header "K: V"]... [--body <str>] [--raw] [--timeout-ms <n>]';
+function parseCliArgs(argv) {
+  if (argv[0] !== "fetch") return { ok: false, error: `unknown command: ${argv[0] ?? "(none)"}` };
+  const rest = argv.slice(1);
+  let url;
+  let method;
+  let headers;
+  let body;
+  let raw;
+  let timeoutMs;
+  for (let i = 0; i < rest.length; i++) {
+    const arg = rest[i];
+    if (arg === "--raw") {
+      raw = true;
+      continue;
+    }
+    if (arg === "--method" || arg === "--header" || arg === "--body" || arg === "--timeout-ms") {
+      const value = rest[++i];
+      if (value === void 0) return { ok: false, error: `${arg} requires a value` };
+      if (arg === "--method") {
+        if (value !== "GET" && value !== "HEAD" && value !== "POST") {
+          return { ok: false, error: `invalid --method: ${value}` };
+        }
+        method = value;
+      } else if (arg === "--header") {
+        const sep = value.indexOf(": ");
+        if (sep <= 0) return { ok: false, error: `malformed --header (expected "Key: Value"): ${value}` };
+        headers ??= {};
+        headers[value.slice(0, sep)] = value.slice(sep + 2);
+      } else if (arg === "--body") {
+        body = value;
+      } else {
+        const n = Number(value);
+        if (!Number.isFinite(n) || n <= 0) return { ok: false, error: `invalid --timeout-ms: ${value}` };
+        timeoutMs = n;
+      }
+      continue;
+    }
+    if (arg.startsWith("--")) return { ok: false, error: `unknown flag: ${arg}` };
+    if (url !== void 0) return { ok: false, error: `unexpected argument: ${arg}` };
+    url = arg;
+  }
+  if (!url) return { ok: false, error: "missing <url>" };
+  const opts = { url };
+  if (method !== void 0) opts.method = method;
+  if (headers !== void 0) opts.headers = headers;
+  if (body !== void 0) opts.body = body;
+  if (raw !== void 0) opts.raw = raw;
+  if (timeoutMs !== void 0) opts.timeoutMs = timeoutMs;
+  return { ok: true, opts };
+}
+async function main() {
+  const parsed = parseCliArgs(process.argv.slice(2));
+  if (!parsed.ok) {
+    process.stderr.write(`${parsed.error}
+${USAGE}
+`);
+    return 2;
+  }
+  try {
+    const result = await fetchUrl(parsed.opts);
+    process.stdout.write(`${result.output}
+`);
+    return 0;
+  } catch (err) {
+    process.stderr.write(`fetch failed: ${err instanceof Error ? err.message : String(err)}
+`);
+    return 1;
+  }
+}
+function isMainEntry() {
+  if (!process.argv[1]) return false;
+  try {
+    return realpathSync(fileURLToPath(import.meta.url)) === realpathSync(resolve(process.argv[1]));
+  } catch {
+    return false;
+  }
+}
+if (isMainEntry()) {
+  main().then((code) => {
+    process.exitCode = code;
+  });
+}
+export {
+  parseCliArgs
+};