pi-quiver 3.0.0 → 3.1.0

package/CHANGELOG.md

@@ -8,6 +8,20 @@ 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.
 
+## v3.1.0 - 2026-07-04
+
+- **`fetch` auto-routes GitHub URLs through the `gh` CLI.** `github.com` issue,
+  PR, and repo-root URLs are served by `gh issue|pr view --comments` /
+  `gh repo view` and returned through the existing size gate, tagged with a
+  `Source: gh ...` header. Falls back silently to the HTTP path when `gh` is
+  absent, unauthenticated, or errors; `raw=true` forces the rendered page. No
+  new npm dependencies. `gh` is documented as an optional runtime binary in the
+  new README Prerequisites section.
+
+## v3.0.1 - 2026-07-04
+
+- **`release.yml` posts GitHub Release notes.** A new `release-notes` job (`needs: publish`, `contents: write`) extracts the CHANGELOG section matching the pushed tag with `awk` and publishes it as the GitHub Release body via `gh release create` (falling back to `gh release edit`). No LLM or API key; only `github.token`.
+
 ## v3.0.0 - 2026-07-02
 
 - **Distribution moved from git-tag pins to npm, and the package renamed

package/README.md

@@ -11,6 +11,18 @@ A small pack of [Pi coding-agent](https://github.com/badlogic/pi-mono) extension
 | `session-name.ts` | `/session-name` | Name work sessions. Manual `/session-name [name]` always works. **OFF by default:** when opted in via `settings.json`, after the first agent turn it asks the current model for a concise session name + short tab label and applies them, and renames the **Ghostty** tab via OSC 2 (only when the active terminal is really Ghostty), re-asserting it each turn so the tab tracks the session name. |
 | `sword-header.ts` | `/builtin-header` | Replace the TUI startup logo with a theme-colored ASCII greatsword (hilt = accent, blade = text). **OFF by default:** only installs the header when opted in via `settings.json`. `/builtin-header` restores the built-in header at runtime. |
 
+## Prerequisites
+
+The npm package's bundled JS deps install automatically on `pi install` - nothing to set up there. A few **runtime system binaries** are optional; each degrades gracefully when absent:
+
+| Prerequisite | Needed by | If absent |
+|---|---|---|
+| `gh` (GitHub CLI, installed + `gh auth login`) | `fetch` GitHub issue/PR/repo 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. |
+
+None is a hard install-time dependency of the package; they are tools you provide in the environment where pi runs.
+
 ### fetch — content routing & context hygiene
 
 `fetch` is the main way an agent pulls external bytes into context. This extension routes responses by type to keep context tight:
@@ -37,8 +49,11 @@ A small pack of [Pi coding-agent](https://github.com/badlogic/pi-mono) extension
 
 **JSON:** Pretty-printed with 2-space indent before the gate.
 
+**GitHub URLs -> `gh`:** `github.com` issue (`/issues/{n}`), PR (`/pull/{n}`), and repo-root (`/{owner}/{repo}`) URLs are served by running the `gh` CLI (`gh issue|pr view --comments`, `gh repo view`) and returning its output, tagged with a `Source: gh ...` header and run through the same size gate. Requires `gh` (see [Prerequisites](#prerequisites)); if `gh` is missing or the call fails, `fetch` silently falls back to the normal HTTP path. Pass `raw=true` to force the rendered HTML page. All other GitHub paths (`tree`, `blob`, `raw`, `releases`, gists, ...) use the HTTP path unchanged. Routing is also skipped (plain HTTP used) when the request is non-GET, carries a body, or sets custom headers. gh output is bounded by a 10 MB buffer and run through the same size gate (spilled to a file when large), not the 1 MB HTTP download cap.
+
 **Parameters:**
 - `raw=true`: Skip HTML→Markdown and JSON pretty-printing; return decoded body as-is (still subject to the size gate).
+- `raw=true` also bypasses GitHub `gh` routing (forces the HTTP/rendered path).
 
 **Truncation:** Parsable content over 1 MB is truncated with a `(truncated to 1MB)` note; binary over 50 MB notes `(truncated to 50MB)`.
 
@@ -68,7 +83,7 @@ A small pack of [Pi coding-agent](https://github.com/badlogic/pi-mono) extension
 
 Python is pinned to **3.14** and is not configurable.
 
-**Runtime dependencies:** `unpdf` (shipped in the npm package, installed automatically on `pi install`). `uv` and LibreOffice (`soffice`) are optional system binaries detected at runtime: without `uv`, PDFs still convert via the `unpdf` fallback; without `soffice`, office inputs error while PDFs are unaffected.
+**Runtime dependencies:** `unpdf` (shipped in the npm package, installed automatically on `pi install`). `uv` and LibreOffice (`soffice`) are optional system binaries detected at runtime: without `uv`, PDFs still convert via the `unpdf` fallback; without `soffice`, office inputs error while PDFs are unaffected. See [Prerequisites](#prerequisites) for the consolidated list.
 
 **Licensing note:** `pymupdf4llm`/PyMuPDF are **AGPL-3.0**. This package ships none of their code — `uv` downloads the wheel from PyPI onto your machine at runtime, and it runs as a **separate subprocess** (never imported or linked into this TypeScript). The arms-length process boundary keeps pi-quiver' MIT license intact; the AGPL governs PyMuPDF itself, whose source is public. This holds only while the boundary stays subprocess-only (no vendoring/importing the wheel).
 

package/fetch.ts

@@ -15,6 +15,8 @@ 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 type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { formatSize, keyHint } from "@earendil-works/pi-coding-agent";
 import { Text } from "@earendil-works/pi-tui";
@@ -35,6 +37,148 @@ interface FetchToolDetails {
 	spilled?: boolean;
 	file?: string;
 	lines?: number;
+	via?: "gh";
+	ghCommand?: string;
+}
+
+type GhTarget =
+	| { kind: "issue"; url: string }
+	| { kind: "pr"; url: string }
+	| { kind: "repo"; slug: string };
+
+const RESERVED_OWNERS = new Set([
+	"orgs", "users", "sponsors", "topics", "marketplace", "apps",
+	"collections", "stars", "settings", "notifications", "codespaces",
+	"features", "trending", "security", "customer-stories",
+]);
+const GH_NAME = /^[A-Za-z0-9._-]+$/;
+
+export function classifyGitHubTarget(url: URL): GhTarget | null {
+	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 === 2) {
+		return { kind: "repo", slug: `${owner}/${repo}` };
+	}
+	return null;
+}
+
+export function buildGhArgs(target: GhTarget): string[] {
+	if (target.kind === "issue") return ["issue", "view", target.url, "--comments"];
+	if (target.kind === "pr") return ["pr", "view", target.url, "--comments"];
+	return ["repo", "view", target.slug];
+}
+
+const GH_MAX_BUFFER = 10_000_000; // 10 MB — an order above PARSABLE_MAX_BYTES
+
+type GhResult = { ok: true; stdout: string } | { ok: false };
+export type GhRunner = (args: string[], timeoutMs: number, signal?: AbortSignal) => Promise<GhResult>;
+
+const execFileAsync = promisify(execFile);
+
+export const runGh: GhRunner = 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 };
+	}
+};
+
+interface GhRoutingParams {
+	raw?: boolean;
+	method?: string;
+	body?: string;
+	headers?: Record<string, string>;
+	timeoutMs?: number;
+}
+
+export function planGhRouting(params: GhRoutingParams, url: URL): GhTarget | null {
+	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: GhTarget): string {
+	if (target.kind === "issue") return "issue view --comments";
+	if (target.kind === "pr") return "pr view --comments";
+	return "repo view";
+}
+
+function ghSourceLine(target: GhTarget, ref: string): string {
+	if (target.kind === "issue") return `gh issue view ${ref} --comments`;
+	if (target.kind === "pr") return `gh pr view ${ref} --comments`;
+	return `gh repo view ${ref}`;
+}
+
+function renderGhResult(target: GhTarget, stdout: string): { content: { type: "text"; text: string }[]; details: FetchToolDetails } {
+	const body = stdout.trimEnd();
+	const ref = target.kind === "repo" ? target.slug : target.url;
+	const { spill, bytes, lines } = applyGate(body);
+	const baseDetails: FetchToolDetails = {
+		url: ref,
+		bytes,
+		lines,
+		category: "markdown",
+		via: "gh",
+		ghCommand: ghCommandLabel(target),
+	};
+	const source = `Source: ${ghSourceLine(target, ref)}`;
+	if (!spill) {
+		return {
+			content: [{ type: "text", text: [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 {
+		content: [{
+			type: "text",
+			text: [
+				source,
+				`Body: ${formatSize(bytes)} across ${lines} lines — 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 },
+	};
+}
+
+export async function executeGhRouting(
+	params: GhRoutingParams,
+	url: URL,
+	signal: AbortSignal | undefined,
+	runner: GhRunner = runGh,
+): Promise<{ content: { type: "text"; text: string }[]; details: FetchToolDetails } | null> {
+	const target = planGhRouting(params, url);
+	if (!target) return null;
+	const gh = await runner(buildGhArgs(target), params.timeoutMs ?? DEFAULT_TIMEOUT_MS, signal);
+	if (!gh.ok) return null;
+	return renderGhResult(target, gh.stdout);
 }
 
 const PARSABLE_MAX_BYTES = 1_000_000; // text/markdown/json download ceiling
@@ -307,13 +451,14 @@ export default function fetchExtension(pi: ExtensionAPI) {
 		name: "fetch",
 		label: "Fetch URL",
 		description:
-			"Fetch a URL over HTTP(S). HTML is extracted to Markdown (readability + turndown). Binary content (images, PDFs, archives) is saved untouched to a temp file and only a path is returned. Text/Markdown/JSON over 32KB or 1000 lines is written to a temp file with a 60-line preview; smaller content is returned inline. Parsable downloads are capped at 1MB, binary at 50MB.",
+			"Fetch a URL over HTTP(S). HTML is extracted to Markdown (readability + turndown). Binary content (images, PDFs, archives) is saved untouched to a temp file and only a path is returned. Text/Markdown/JSON over 32KB or 1000 lines is written to a temp file with a 60-line preview; smaller content is returned inline. Parsable downloads are capped at 1MB, binary at 50MB. GitHub issue/PR/repo URLs are served via the gh CLI when available (falls back to HTTP otherwise).",
 		promptSnippet: "Fetch the contents of a URL",
 		promptGuidelines: [
 			"Use fetch when the user provides a URL or asks to read web content.",
 			"Binary responses return a file path only — pass that path to a tool that can process the bytes; do not expect inline content.",
 			"When the body is written to a file, grep it or read with offset/limit. Converted Markdown is grep-able by heading (^#).",
 			"Pass raw=true to skip Markdown/JSON conversion and get the decoded body as-is (still subject to the size gate).",
+			"GitHub issue/PR/repo links are fetched through the gh CLI automatically; pass raw=true to force the rendered HTML page.",
 		],
 		parameters: Type.Object({
 			url: Type.String({ description: "Absolute http(s) URL" }),
@@ -340,6 +485,9 @@ export default function fetchExtension(pi: ExtensionAPI) {
 				throw new Error(`Unsupported protocol: ${url.protocol}`);
 			}
 
+			const ghResult = await executeGhRouting(params, url, signal ?? undefined);
+			if (ghResult) return ghResult;
+
 			const headers = new Headers(params.headers ?? {});
 			if (!headers.has("user-agent")) headers.set("user-agent", FIREFOX_UA);
 			if (!headers.has("accept")) headers.set("accept", DEFAULT_ACCEPT);
@@ -493,9 +641,11 @@ export default function fetchExtension(pi: ExtensionAPI) {
 				return new Text(theme.fg("error", firstLine), 0, 0);
 			}
 
+			const isGh = details?.via === "gh";
 			const status = details?.status;
-			const statusStyled =
-				status === undefined
+			const statusStyled = isGh
+				? theme.fg("success", "gh")
+				: status === undefined
 					? theme.fg("muted", "HTTP ?")
 					: status >= 200 && status < 300
 						? theme.fg("success", `HTTP ${status}`)
@@ -505,7 +655,9 @@ export default function fetchExtension(pi: ExtensionAPI) {
 
 			const sep = theme.fg("dim", " · ");
 			const parts: string[] = [statusStyled];
-			if (details?.contentType) {
+			if (isGh) {
+				if (details?.ghCommand) parts.push(theme.fg("muted", details.ghCommand));
+			} else if (details?.contentType) {
 				parts.push(theme.fg("muted", details.contentType.split(";")[0].trim()));
 			}
 			if (typeof details?.bytes === "number") {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-quiver",
-  "version": "3.0.0",
+  "version": "3.1.0",
   "description": "Personal pack of Pi coding-agent extensions. First-party-quality tools that keep context clean. Ships a context-safe fetch tool and a doc_to_md PDF/DOCX/PPTX-to-Markdown converter.",
   "author": "Jacek Juraszek",
   "license": "MIT",
@@ -37,9 +37,10 @@
     "CHANGELOG.md"
   ],
   "scripts": {
+    "check:agents-core": "node scripts/check-agents-core.mjs",
     "test": "node --test \"*.test.ts\"",
     "typecheck": "npx -y tsc --noEmit --allowImportingTsExtensions --target es2022 --module nodenext --moduleResolution nodenext --strict --skipLibCheck --esModuleInterop --resolveJsonModule --lib es2022 --types node fetch.ts fetch.test.ts doc_to_md.ts doc_to_md.test.ts session-name.ts session-name.test.ts sword-header.ts sword-header.test.ts extension-config.ts types/turndown-plugin-gfm.d.ts",
-    "test:all": "npm run test && npm run typecheck"
+    "test:all": "npm run check:agents-core && npm run test && npm run typecheck"
   },
   "pi": {
     "extensions": [