@danypops/pi-packed 0.1.0

package/README.md

@@ -0,0 +1,92 @@
+# pi-packed
+
+Package service for the [Pi](https://github.com/earendil-works/pi-coding-agent) agent —
+DNF-style package management that both **you** and the **agent** can use.
+
+The agent gets tools (`pkg_search`, `pkg_info`, `pkg_install`); you get a CLI
+(`packed`) and an interactive TUI (`/packages`). All logic lives in a
+long-running Bun service — the extension is a thin seam.
+
+```
+┌─ Pi extension seam (extension/src) ───────────┐
+│ pkg_search/pkg_info/pkg_install tools         │
+│ /packages TUI · session_start notify          │
+│ thin: exec `bun src/cli.ts …`, confirm gates  │
+└───────────────┬───────────────────────────────┘
+                │ CLI (same hexagon ports)
+┌─ Bun service (src/) ──────────────────────────┼──────────┐
+│ cli.ts (command table) · service.ts (fetch)   │          │
+│ daemon: watcher (update drift) + catalogSync  │          │
+│ npm registry adapter · pi install exec adapter│          │
+└───────────────────────────────────────────────┴──────────┘
+```
+
+## Quickstart
+
+```bash
+bun test                          # 52 tests
+bun src/cli.ts search lsp         # one-shot, direct to npm
+bun src/cli.ts serve &            # long-running service (warm cache + watcher)
+bun src/cli.ts updates            # diff installed vs latest
+
+# In Pi:
+pi -e /path/to/pi-packed/extension/src/index.ts   # ephemeral
+# or: pi install git:github.com/DanyPops/pi-packed
+/packages                                              # interactive panel
+```
+
+## CLI
+
+| Command | What |
+|---|---|
+| `packed search <q> [--limit N] [--json]` | npm search scoped to `keywords:pi-package` |
+| `packed info <name> [--json]` | version, repo, pi manifest, size |
+| `packed updates [--cached]` | drift vs dist-tags.latest (`--cached` = watcher snapshot) |
+| `packed installed` | parse `~/.pi/agent/settings.json` (+ node_modules versions) |
+| `packed catalog` | full pi-package snapshot (hot browse) |
+| `packed install <source>` | allowlisted: `npm:` / `git:` / `https://` |
+| `packed remove <name>` | bare npm name |
+| `packed serve` | daemon: HTTP API + watcher + catalog sync + idle self-exit |
+
+## Service API (loopback + bearer token)
+
+`GET /health` · `GET /search?q=&limit=` · `GET /info?name=` · `POST /install`
+· `GET /updates` · `GET /catalog`
+
+State in `~/.cache/pi-packed/` (`PI_PACKED_HOME`): `token`, `port`,
+`updates.json`, `catalog.json`. Env knobs: `PI_PACKED_WATCH_SECS` (default
+30min), `PI_PACKED_CATALOG_SECS` (6h), `PI_PACKED_IDLE_SECS` (10min),
+`PI_PACKED_PI_HOME`, `PACKED_CLI` / `PACKED_BIN` (seam overrides).
+
+## Architecture (patterns)
+
+| Pattern | Where |
+|---|---|
+| Ports & Adapters | `ports.ts` interfaces; drivers: HTTP, CLI, watcher, tests; driven: npm, pi exec |
+| Proxy | daemon = caching/protection proxy of npm; `DaemonRegistry` = remote proxy |
+| Facade | lean JSON over npm's verbose documents |
+| Event-driven | watcher + catalogSync produce snapshots; seam consumes on `session_start` → `ctx.ui.notify` (event-carried state, no callbacks) |
+| Command | `cli.ts` command table (go-tool/Cobra convention, zero deps) |
+| Deep module | tiny API surface, rich internals — one package, no sprawl |
+
+## Decisions
+
+- **Bun/TS over Go/Rust**: one language end-to-end, no build step (Bun runs
+  TS directly), `pi install git:…` works without binaries. Service is
+  IO-bound; runtime perf is irrelevant.
+- **No Cobra/urfave**: agent-first CLI; stdlib-style flag parsing with
+  flags-anywhere support (LLMs emit flags in random positions).
+- **npm registry is the source of truth** (5,500+ pkgs): pi.dev has no API
+  (`/api/*` → "reserved for future features"), its gallery is curated HTML
+  (~50/page, server-side `?name=` filter). Catalog sync paginates
+  `keywords:pi-package` (250/page) into `catalog.json`, TTL 6h — npm's
+  search API has no ETag, so conditional revalidation is impossible.
+- **Install validation** is an allowlist regex (defense-in-depth on top of
+  the bearer token): no shell metacharacters, ever.
+
+## Roadmap
+
+- `pi.dev` JSON API when it ships (currently 501 reserved)
+- `replicate.npmjs.com` changes feed for near-real-time catalog
+- Unix socket transport; `bun build --compile` single-binary distribution
+- `/packages` remote-browse view fed by `catalog.json`

package/extension/src/index.ts

@@ -0,0 +1,41 @@
+/**
+ * pi-packed — Pi extension seam.
+ *
+ * Thin by design: registers agent tools (pkg_search/pkg_info/pkg_install),
+ * the /packages command, and a session_start update notification. ALL logic
+ * lives in the Bun service (src/): registry access, caching, watcher,
+ * catalog sync, install execution.
+ *
+ * Install: pi install git:github.com/DanyPops/pi-packed
+ */
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { registerTools } from "./tools.js";
+import { showPackages } from "./tui.js";
+import { runPacked } from "./packed.js";
+import { formatUpdateNotice } from "./model.js";
+import type { UpdatesSnapshot } from "./packed.js";
+
+export default function (pi: ExtensionAPI) {
+	registerTools(pi);
+
+	pi.registerCommand("packages", {
+		description: "Browse and manage installed Pi packages (pi-packed)",
+		handler: async (_args, ctx) => {
+			await showPackages(ctx);
+		},
+	});
+
+	// The watcher (daemon side) produces the snapshot; the seam consumes it
+	// on Pi's own lifecycle event — that's the whole event-driven story.
+	pi.on("session_start", async (_event, ctx) => {
+		if (!ctx.hasUI) return;
+		try {
+			const snap = await runPacked<UpdatesSnapshot>(["updates", "--cached"], 3_000);
+			if (snap.updates?.length) {
+				ctx.ui.notify(`${formatUpdateNotice(snap.updates)} — /packages to review`, "info");
+			}
+		} catch {
+			// packed missing or daemon down — stay silent, never block startup.
+		}
+	});
+}

package/extension/src/model.ts

@@ -0,0 +1,50 @@
+/**
+ * model.ts — pure row logic for the /packages panel. No I/O: vitest drives
+ * this directly (the TUI component is a thin shell over these functions).
+ */
+import type { InstalledPkg, UpdateEntry } from "./packed.js";
+
+export interface Row {
+	name: string;
+	version: string; // pinned ?? installed
+	latest?: string;
+	hasUpdate: boolean;
+}
+
+export type ViewMode = "all" | "updates";
+
+export function mergeRows(installed: InstalledPkg[], updates: UpdateEntry[]): Row[] {
+	const byName = new Map(updates.map((u) => [u.name, u]));
+	return installed
+		.map((p) => {
+			const u = byName.get(p.name);
+			return {
+				name: p.name,
+				version: p.pinned ?? p.installed ?? "?",
+				latest: u?.latest,
+				hasUpdate: u !== undefined,
+			};
+		})
+		.sort((a, b) => a.name.localeCompare(b.name));
+}
+
+export function visibleRows(rows: Row[], mode: ViewMode): Row[] {
+	if (mode === "updates") return rows.filter((r) => r.hasUpdate);
+	return rows;
+}
+
+export function nextMode(mode: ViewMode): ViewMode {
+	return mode === "all" ? "updates" : "all";
+}
+
+export function filterRows(rows: Row[], query: string): Row[] {
+	const q = query.trim().toLowerCase();
+	if (!q) return rows;
+	return rows.filter((r) => r.name.toLowerCase().includes(q));
+}
+
+export function formatUpdateNotice(updates: UpdateEntry[]): string {
+	const names = updates.slice(0, 3).map((u) => `${u.name} ${u.installed}→${u.latest}`);
+	const more = updates.length > 3 ? ` +${updates.length - 3} more` : "";
+	return `${updates.length} package update(s): ${names.join(", ")}${more}`;
+}

package/extension/src/packed.ts

@@ -0,0 +1,90 @@
+/**
+ * packed.ts — the ONLY place the seam touches the service side.
+ * Thin exec wrapper: every call is `bun <pi-packed>/src/cli.ts <cmd>`.
+ * No registry, daemon, or npm knowledge lives here.
+ */
+import { execFile } from "node:child_process";
+
+export interface InstalledPkg {
+	name: string;
+	pinned?: string;
+	installed?: string;
+}
+
+export interface UpdateEntry {
+	name: string;
+	installed: string;
+	latest: string;
+	detectedAt?: string;
+}
+
+export interface UpdatesSnapshot {
+	checkedAt?: string;
+	updates: UpdateEntry[];
+}
+
+export interface SearchResult {
+	name: string;
+	version: string;
+	description?: string;
+	date?: string;
+}
+
+export interface SearchResponse {
+	query: string;
+	total: number;
+	results: SearchResult[];
+}
+
+export interface PackageInfo {
+	name: string;
+	version: string;
+	description?: string;
+	homepage?: string;
+	repository?: string;
+	license?: string;
+	keywords?: string[];
+	pi?: Record<string, unknown>;
+	modified?: string;
+	unpackedSize?: number;
+}
+
+/** Path to the pi-packed CLI entry (resolved relative to this file). */
+export function cliPath(): string {
+	if (process.env["PACKED_CLI"]) return process.env["PACKED_CLI"];
+	return new URL("../../src/cli.ts", import.meta.url).pathname;
+}
+
+export function packedCmd(): { bin: string; prefix: string[] } {
+	if (process.env["PACKED_BIN"]) return { bin: process.env["PACKED_BIN"], prefix: [] };
+	return { bin: process.env["PACKED_BUN"] ?? "bun", prefix: [cliPath()] };
+}
+
+function exec(cmd: string, args: string[], timeoutMs: number): Promise<{ stdout: string; stderr: string }> {
+	return new Promise((resolve, reject) => {
+		execFile(cmd, args, { timeout: timeoutMs, maxBuffer: 16 * 1024 * 1024 }, (err, stdout, stderr) => {
+			if (err) {
+				reject(new Error(stderr?.trim() || err.message));
+				return;
+			}
+			resolve({ stdout, stderr });
+		});
+	});
+}
+
+export async function runPacked<T>(args: string[], timeoutMs = 15_000): Promise<T> {
+	const { bin, prefix } = packedCmd();
+	const { stdout } = await exec(bin, [...prefix, ...args, "--json"], timeoutMs);
+	try {
+		return JSON.parse(stdout) as T;
+	} catch {
+		throw new Error(`packed ${args[0]}: invalid JSON: ${stdout.slice(0, 200)}`);
+	}
+}
+
+/** Text output variant for install/remove (human-readable pi output). */
+export async function runPackedText(args: string[], timeoutMs = 180_000): Promise<string> {
+	const { bin, prefix } = packedCmd();
+	const { stdout, stderr } = await exec(bin, [...prefix, ...args], timeoutMs);
+	return [stdout.trim(), stderr.trim()].filter(Boolean).join("\n");
+}

package/extension/src/tools.ts

@@ -0,0 +1,98 @@
+/**
+ * tools.ts — agent-facing tools. Thin by design: descriptions teach the
+ * agent the packed CLI surface; logic lives in the Bun service.
+ */
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+import { runPacked, runPackedText } from "./packed.js";
+import type { PackageInfo, SearchResponse } from "./packed.js";
+
+function text(t: string, details: Record<string, unknown> = {}) {
+	return { content: [{ type: "text" as const, text: t }], details };
+}
+
+export function registerTools(pi: ExtensionAPI): void {
+	pi.registerTool({
+		name: "pkg_search",
+		label: "Pi Package Search",
+		description:
+			"Search Pi packages (extensions, skills, themes, prompts) on the npm registry. " +
+			"Scoped to the pi-package keyword automatically. Returns name, version, description.",
+		parameters: Type.Object({
+			query: Type.String({ description: "Search terms, e.g. 'lsp' or 'telegram'" }),
+			limit: Type.Optional(Type.Number({ description: "Max results (default 10, max 50)" })),
+		}),
+		async execute(_id, params, _signal, _onUpdate, _ctx) {
+			try {
+				const r = await runPacked<SearchResponse>(
+					["search", params.query, "--limit", String(params.limit ?? 10)],
+				);
+				if (r.results.length === 0) return text(`No Pi packages found for "${params.query}".`);
+				const lines = r.results.map(
+					(p, i) => `${i + 1}. ${p.name}@${p.version}\n   ${p.description ?? ""}`,
+				);
+				return text(
+					`Found ${r.total} pi package(s) (showing ${r.results.length}):\n\n${lines.join("\n")}`,
+					{ results: r.results, total: r.total },
+				);
+			} catch (e) {
+				return text(`pkg_search failed: ${e instanceof Error ? e.message : e}`);
+			}
+		},
+	});
+
+	pi.registerTool({
+		name: "pkg_info",
+		label: "Pi Package Info",
+		description:
+			"Show details for a Pi package: latest version, description, repository, " +
+			"declared pi resources (extensions/skills/themes/prompts), size, license.",
+		parameters: Type.Object({
+			name: Type.String({ description: "npm package name, e.g. 'pi-lsp' or '@scope/pkg'" }),
+		}),
+		async execute(_id, params, _signal, _onUpdate, _ctx) {
+			try {
+				const info = await runPacked<PackageInfo>(["info", params.name]);
+				const lines = [
+					`${info.name}@${info.version}`,
+					info.description ?? "",
+					info.repository ? `repo: ${info.repository}` : "",
+					info.license ? `license: ${info.license}` : "",
+					info.pi ? `provides: ${Object.keys(info.pi).join(", ")}` : "",
+					info.unpackedSize ? `size: ${(info.unpackedSize / 1024).toFixed(0)} KB` : "",
+					info.modified ? `modified: ${info.modified}` : "",
+				].filter(Boolean);
+				return text(lines.join("\n"), { info });
+			} catch (e) {
+				return text(`pkg_info failed: ${e instanceof Error ? e.message : e}`);
+			}
+		},
+	});
+
+	pi.registerTool({
+		name: "pkg_install",
+		label: "Pi Package Install",
+		description:
+			"Install a Pi package (pi install). Supports npm:<pkg>[@ver], git:<host>/<owner>/<repo>[@ref], " +
+			"or https:// URLs. Packages execute arbitrary code — the user confirms every install.",
+		parameters: Type.Object({
+			source: Type.String({ description: "e.g. 'npm:pi-lsp', 'npm:@scope/pkg@1.2.3', 'git:github.com/u/r@v1'" }),
+		}),
+		async execute(_id, params, _signal, _onUpdate, ctx) {
+			if (!ctx.hasUI) {
+				return text("pkg_install requires an interactive session (the user must confirm).");
+			}
+			const ok = await ctx.ui.confirm(
+				"Install Pi package",
+				`Run: pi install ${params.source}\n\nPackages execute arbitrary code. Continue?`,
+			);
+			if (!ok) return text("Install cancelled by user.");
+			try {
+				const out = await runPackedText(["install", params.source]);
+				return text(out || `Installed ${params.source}. Reload with /reload to activate.`);
+			} catch (e) {
+				return text(`install failed: ${e instanceof Error ? e.message : e}`);
+			}
+		},
+	});
+}

package/extension/src/tui.ts

@@ -0,0 +1,222 @@
+/**
+ * tui.ts — /packages interactive panel. Follows the pi-extension-manager
+ * idiom: ctx.ui.custom with Container/DynamicBorder layout, header hints,
+ * type-to-filter (/), Tab view modes, Enter → actions, r refresh, esc close.
+ * All data flows through the packed CLI (thin seam).
+ */
+import type { ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
+import { DynamicBorder, rawKeyHint } from "@earendil-works/pi-coding-agent";
+import { Container, Input, Spacer, truncateToWidth, visibleWidth } from "@earendil-works/pi-tui";
+import { filterRows, mergeRows, nextMode, visibleRows } from "./model.js";
+import type { Row, ViewMode } from "./model.js";
+import { runPacked, runPackedText } from "./packed.js";
+import type { InstalledPkg, UpdatesSnapshot } from "./packed.js";
+
+interface PanelAction {
+	type: "menu" | "refresh";
+	row?: Row;
+}
+
+async function loadRows(): Promise<{ rows: Row[]; error?: string }> {
+	try {
+		const [installed, snap] = await Promise.all([
+			runPacked<InstalledPkg[]>(["installed"]),
+			runPacked<UpdatesSnapshot>(["updates", "--cached"], 5_000).catch(() => ({ updates: [] }) as UpdatesSnapshot),
+		]);
+		return { rows: mergeRows(installed, snap.updates ?? []) };
+	} catch (e) {
+		return { rows: [], error: e instanceof Error ? e.message : String(e) };
+	}
+}
+
+export async function showPackages(ctx: ExtensionCommandContext): Promise<void> {
+	if (!ctx.hasUI) {
+		ctx.ui.notify("/packages requires interactive mode", "warning");
+		return;
+	}
+
+	let { rows, error } = await loadRows();
+	if (error) {
+		ctx.ui.notify(`packed unavailable: ${error}`, "error");
+		return;
+	}
+
+	// Panel loop: actions resolve the component, run outside it, then reopen.
+	for (;;) {
+		const action = await renderPanel(ctx, rows);
+		if (!action) return; // closed
+
+		if (action.type === "refresh") {
+			({ rows, error } = await loadRows());
+			if (error) ctx.ui.notify(`refresh failed: ${error}`, "error");
+			continue;
+		}
+
+		const row = action.row;
+		if (!row) continue;
+
+		const choice = await ctx.ui.select(
+			`${row.name}@${row.version}${row.hasUpdate ? `  →  ${row.latest}` : ""}`,
+			[
+				...(row.hasUpdate ? [`Update to ${row.latest}`] : []),
+				"Remove",
+				"Cancel",
+			],
+		);
+
+		if (choice?.startsWith("Update")) {
+			ctx.ui.notify(`Updating ${row.name}…`, "info");
+			try {
+				await runPackedText(["install", `npm:${row.name}@${row.latest}`]);
+				ctx.ui.notify(`Updated ${row.name} to ${row.latest} (takes effect after /reload)`, "info");
+				row.version = row.latest ?? row.version;
+				row.hasUpdate = false;
+			} catch (e) {
+				ctx.ui.notify(`update failed: ${e instanceof Error ? e.message : e}`, "error");
+			}
+		} else if (choice === "Remove") {
+			const sure = await ctx.ui.confirm("Remove package", `pi remove npm:${row.name}?`);
+			if (sure) {
+				try {
+					await runPackedText(["remove", row.name]);
+					ctx.ui.notify(`Removed ${row.name}`, "info");
+					rows = rows.filter((r) => r.name !== row.name);
+				} catch (e) {
+					ctx.ui.notify(`remove failed: ${e instanceof Error ? e.message : e}`, "error");
+				}
+			}
+		}
+	}
+}
+
+function renderPanel(ctx: ExtensionCommandContext, rows: Row[]): Promise<PanelAction | undefined> {
+	return ctx.ui.custom<PanelAction | undefined>((tui, theme, _kb, done) => {
+		let mode: ViewMode = "all";
+		const searchInput = new Input();
+		let searchActive = false;
+		let filtered = visibleRows(rows, mode);
+		let selectedIndex = 0;
+
+		const maxVisible = 20;
+
+		function applyFilter(): void {
+			filtered = filterRows(visibleRows(rows, mode), searchInput.getValue());
+			selectedIndex = 0;
+		}
+
+		const header = {
+			invalidate() {},
+			render(width: number): string[] {
+				const title = theme.bold("Packages");
+				const outdated = rows.filter((r) => r.hasUpdate).length;
+				const badge = outdated > 0 ? theme.fg("warning", ` ${outdated} update(s)`) : "";
+				const hint = searchActive
+					? rawKeyHint("esc", "clear")
+					: rawKeyHint("enter", "actions") +
+						theme.fg("muted", " · ") +
+						rawKeyHint("/", "filter") +
+						theme.fg("muted", " · ") +
+						rawKeyHint("tab", "view") +
+						theme.fg("muted", " · ") +
+						rawKeyHint("esc", "close");
+				const spacing = Math.max(1, width - visibleWidth(title) - visibleWidth(badge) - visibleWidth(hint));
+				const line1 = truncateToWidth(`${title}${badge}${" ".repeat(spacing)}${hint}`, width, "");
+				const dot = "·";
+				const line2 = truncateToWidth(
+					theme.fg("muted", `view: ${mode} ${dot} r refresh ${dot} ${rows.length} installed`),
+					width,
+					"",
+				);
+				return [line1, line2];
+			},
+		};
+
+		const list = {
+			invalidate() {},
+			render(width: number): string[] {
+				const lines: string[] = [];
+				if (searchActive) lines.push(...searchInput.render(width));
+				lines.push("");
+				if (filtered.length === 0) {
+					lines.push(theme.fg("muted", "  No packages"));
+					return lines;
+				}
+				const start = Math.max(0, Math.min(selectedIndex - Math.floor(maxVisible / 2), filtered.length - maxVisible));
+				const end = Math.min(start + maxVisible, filtered.length);
+				for (let i = start; i < end; i++) {
+					const row = filtered[i]!;
+					const selected = i === selectedIndex;
+					const cursor = selected ? theme.fg("accent", "❯") : " ";
+					const name = selected ? theme.bold(row.name) : row.name;
+					const ver = theme.fg("dim", `@${row.version}`);
+					const upd = row.hasUpdate ? theme.fg("warning", ` ↑${row.latest}`) : "";
+					lines.push(truncateToWidth(`${cursor} ${name}${ver}${upd}`, width, ""));
+				}
+				const hasScroll = start > 0 || end < filtered.length;
+				lines.push(theme.fg("dim", `  ${hasScroll ? `${selectedIndex + 1}/${filtered.length} ` : ""}${mode}`));
+				return lines;
+			},
+		};
+
+		const container = new Container();
+		container.addChild(new Spacer(1));
+		container.addChild(new DynamicBorder());
+		container.addChild(new Spacer(1));
+		container.addChild(header);
+		container.addChild(new Spacer(1));
+		container.addChild(list);
+		container.addChild(new Spacer(1));
+		container.addChild(new DynamicBorder());
+
+		return {
+			render: (width: number) => container.render(width),
+			invalidate: () => container.invalidate(),
+			handleInput(data: string) {
+				if (searchActive) {
+					if (data === "\x1b") {
+						searchActive = false;
+						searchInput.setValue?.("");
+						applyFilter();
+					} else if (data === "\r") {
+						searchActive = false;
+					} else {
+						searchInput.handleInput(data);
+						applyFilter();
+					}
+					tui.requestRender();
+					return;
+				}
+
+				switch (data) {
+					case "\x1b[A": // up
+						selectedIndex = (selectedIndex - 1 + filtered.length) % Math.max(filtered.length, 1);
+						break;
+					case "\x1b[B": // down
+						selectedIndex = (selectedIndex + 1) % Math.max(filtered.length, 1);
+						break;
+					case "\t":
+						mode = nextMode(mode);
+						applyFilter();
+						break;
+					case "/":
+						searchActive = true;
+						break;
+					case "r":
+						done({ type: "refresh" });
+						return;
+					case "\r": {
+						const row = filtered[selectedIndex];
+						if (row) done({ type: "menu", row });
+						return;
+					}
+					case "\x1b":
+						done(undefined);
+						return;
+					default:
+						return;
+				}
+				tui.requestRender();
+			},
+		};
+	});
+}

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@danypops/pi-packed",
+  "version": "0.1.0",
+  "description": "Package service for the Pi agent: search/info/install/updates + /packages TUI, backed by a long-running Bun service",
+  "type": "module",
+  "keywords": [
+    "pi-package"
+  ],
+  "scripts": {
+    "test": "bun test",
+    "cli": "bun src/cli.ts",
+    "serve": "bun src/cli.ts serve"
+  },
+  "pi": {
+    "extensions": [
+      "extension/src/index.ts"
+    ]
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*",
+    "@earendil-works/pi-tui": "*",
+    "typebox": "*"
+  },
+  "devDependencies": {
+    "bun-types": "latest"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/DanyPops/pi-packed.git"
+  },
+  "files": [
+    "src",
+    "extension",
+    "README.md"
+  ]
+}

package/src/cache.ts

@@ -0,0 +1,19 @@
+/** TTLCache — the smart-proxy concern, nothing more. */
+export class TTLCache {
+	private m = new Map<string, { body: string; expires: number }>();
+	constructor(private ttlMs = 5 * 60_000) {}
+
+	get(key: string): string | undefined {
+		const e = this.m.get(key);
+		if (!e) return undefined;
+		if (Date.now() > e.expires) {
+			this.m.delete(key);
+			return undefined;
+		}
+		return e.body;
+	}
+
+	set(key: string, body: string): void {
+		this.m.set(key, { body, expires: Date.now() + this.ttlMs });
+	}
+}