@danypops/pi-packed 0.1.0

package/src/catalog.ts

@@ -0,0 +1,63 @@
+/**
+ * catalog.ts — event producer #2: bulk snapshot of every pi package.
+ * npm's search API has no ETag/conditional requests (CDN max-age only),
+ * so freshness is TTL-based: resync on serve start + interval.
+ */
+import { writeFile, readFile, mkdir } from "node:fs/promises";
+import { join } from "node:path";
+import type { Pkg, Registry } from "./ports.ts";
+
+export interface CatalogSnapshot {
+	fetchedAt: string;
+	packages: Pkg[];
+}
+
+function catalogPath(dir: string): string {
+	return join(dir, "catalog.json");
+}
+
+export async function saveCatalog(dir: string, snap: CatalogSnapshot): Promise<void> {
+	await mkdir(dir, { recursive: true });
+	await writeFile(catalogPath(dir), JSON.stringify(snap), { mode: 0o600 });
+}
+
+export async function loadCatalog(dir: string): Promise<CatalogSnapshot | undefined> {
+	try {
+		return JSON.parse(await readFile(catalogPath(dir), "utf8")) as CatalogSnapshot;
+	} catch {
+		return undefined;
+	}
+}
+
+export function catalogStale(snap: CatalogSnapshot | undefined, ttlMs: number): boolean {
+	if (!snap?.fetchedAt) return true;
+	return Date.now() - Date.parse(snap.fetchedAt) > ttlMs;
+}
+
+/** Full sync: paginate the whole keyword universe into a lean snapshot. */
+export async function syncCatalog(reg: Registry, dir: string, query = "keywords:pi-package"): Promise<number> {
+	const packages = await reg.searchAll(query);
+	await saveCatalog(dir, { fetchedAt: new Date().toISOString(), packages });
+	return packages.length;
+}
+
+export function startCatalogSync(
+	reg: Registry,
+	dir: string,
+	ttlMs: number,
+	onError?: (e: unknown) => void,
+): () => void {
+	async function sync(): Promise<void> {
+		try {
+			if (catalogStale(await loadCatalog(dir), ttlMs)) {
+				const n = await syncCatalog(reg, dir);
+				console.error(`[packed] catalog synced: ${n} packages`);
+			}
+		} catch (e) {
+			onError?.(e);
+		}
+	}
+	void sync();
+	const timer = setInterval(() => void sync(), ttlMs);
+	return () => clearInterval(timer);
+}

package/src/cli.ts

@@ -0,0 +1,239 @@
+/**
+ * cli.ts — second driving adapter (humans drive the same hexagon ports).
+ * cliRun is pure: ({code, out}) in, no I/O — the entry point prints.
+ * Command table follows the go-tool/Cobra convention; flags may appear
+ * anywhere (agents put them anywhere).
+ */
+import { buildSearchQuery, clampLimit } from "./ports.ts";
+import type { Installer, Registry } from "./ports.ts";
+import { readInstalledPackages } from "./installed.ts";
+import { checkUpdates, loadUpdates } from "./watcher.ts";
+import { loadCatalog } from "./catalog.ts";
+import { NAME_RE } from "./install.ts";
+
+const SOURCE_RE = /^(npm:[A-Za-z0-9@._/-]+|git:[A-Za-z0-9@:._/-]+|https:\/\/[A-Za-z0-9@:._/?=&%~-]+)$/;
+
+const USAGE = `packed — package service for the Pi agent
+
+usage:
+  packed search <query> [--limit N] [--json]   search pi packages on npm
+  packed info <name> [--json]                  package details
+  packed updates [--cached] [--json]           available updates (cached = daemon snapshot)
+  packed installed [--json]                    installed pi packages
+  packed catalog [--json]                      full pi-package catalog snapshot
+  packed install <source>                      pi install npm:|git:|https://…
+  packed remove <name>                         remove by bare npm name
+  packed serve                                 run the long-running daemon
+  packed service                               print a systemd user unit
+  packed version                               print version
+`;
+
+export interface CliDeps {
+	reg: Registry;
+	inst: Installer;
+	stateDir: string;
+	piHome: string;
+	execPath?: string; // bun binary (defaults to process.execPath)
+	cliPath?: string; // this CLI's entry file (for the systemd unit)
+}
+
+export interface CliResult {
+	code: number;
+	out: string;
+}
+
+interface Flags {
+	json: boolean;
+	limit: number;
+	cached: boolean;
+}
+
+function parseFlags(rest: string[]): { flags: Flags; pos: string[] } {
+	const flags: Flags = { json: false, limit: 10, cached: false };
+	const pos: string[] = [];
+	for (let i = 0; i < rest.length; i++) {
+		const a = rest[i]!;
+		if (a === "--json") flags.json = true;
+		else if (a === "--cached") flags.cached = true;
+		else if (a === "--limit" && i + 1 < rest.length) flags.limit = Number(rest[++i]) || 10;
+		else if (a.startsWith("--limit=")) flags.limit = Number(a.slice(8)) || 10;
+		else pos.push(a);
+	}
+	return { flags, pos };
+}
+
+type Command = (rest: string[], d: CliDeps, flags: Flags, pos: string[]) => Promise<CliResult>;
+
+const ok = (out: string): CliResult => ({ code: 0, out });
+const fail = (out: string, code = 1): CliResult => ({ code, out });
+const usageErr = (out: string): CliResult => ({ code: 2, out });
+
+const commands: Record<string, { usage: string; run: Command }> = {
+	search: {
+		usage: "packed search <query> [--limit N] [--json]",
+		async run(_rest, d, flags, pos) {
+			const q = pos[0];
+			if (!q) return usageErr(`usage: ${commands["search"]!.usage}\n`);
+			const { results, total } = await d.reg.search(buildSearchQuery(q), clampLimit(flags.limit, 10, 50));
+			if (flags.json) return ok(JSON.stringify({ query: q, total, results }) + "\n");
+			if (results.length === 0) return ok(`no pi packages found for "${q}"\n`);
+			let out = `${total} package(s) (showing ${results.length}):\n\n`;
+			for (const p of results) out += `  ${p.name}@${p.version}\n    ${p.description ?? ""}\n`;
+			return ok(out);
+		},
+	},
+
+	info: {
+		usage: "packed info <name> [--json]",
+		async run(_rest, d, flags, pos) {
+			const name = pos[0];
+			if (!name) return usageErr(`usage: ${commands["info"]!.usage}\n`);
+			const info = await d.reg.info(name);
+			if (flags.json) return ok(JSON.stringify(info) + "\n");
+			let out = `${info.name}@${info.version}\n${info.description ?? ""}\n`;
+			if (info.repository) out += `repo: ${info.repository}\n`;
+			if (info.pi) out += `provides: ${Object.keys(info.pi).join(", ")}\n`;
+			return ok(out);
+		},
+	},
+
+	updates: {
+		usage: "packed updates [--cached] [--json]",
+		async run(_rest, d, flags) {
+			let updates;
+			if (flags.cached) {
+				updates = (await loadUpdates(d.stateDir))?.updates ?? [];
+			} else {
+				updates = await checkUpdates(d.reg, readInstalledPackages(d.piHome));
+			}
+			if (flags.json) {
+				return ok(JSON.stringify({ checkedAt: new Date().toISOString(), updates }) + "\n");
+			}
+			if (updates.length === 0) return ok("all pi packages up to date\n");
+			let out = `${updates.length} update(s) available:\n\n`;
+			for (const u of updates) out += `  ${u.name}  ${u.installed} → ${u.latest}\n`;
+			return ok(out + "\nrun: pi update --extensions\n");
+		},
+	},
+
+	installed: {
+		usage: "packed installed [--json]",
+		async run(_rest, d, flags) {
+			const installed = readInstalledPackages(d.piHome);
+			if (flags.json) return ok(JSON.stringify(installed) + "\n");
+			return ok(installed.map((p) => `  ${p.name}@${p.pinned ?? p.installed ?? "?"}\n`).join(""));
+		},
+	},
+
+	catalog: {
+		usage: "packed catalog [--json]",
+		async run(_rest, d, flags) {
+			const snap = await loadCatalog(d.stateDir);
+			const packages = snap?.packages ?? [];
+			if (flags.json) return ok(JSON.stringify(snap ?? { packages: [] }) + "\n");
+			let out = `${packages.length} packages in catalog (fetched ${snap?.fetchedAt ?? "never"})\n\n`;
+			for (const p of packages.slice(0, 50)) out += `  ${p.name}@${p.version}\n`;
+			return ok(out);
+		},
+	},
+
+	install: {
+		usage: "packed install npm:<pkg>[@ver] | git:<host>/<owner>/<repo>[@ref] | https://…",
+		async run(_rest, d, _flags, pos) {
+			const source = pos[0] ?? "";
+			if (!SOURCE_RE.test(source)) return usageErr(`usage: ${commands["install"]!.usage}\n`);
+			try {
+				return ok((await d.inst.install(source)) + "\n");
+			} catch (e) {
+				return fail(`${e instanceof Error ? e.message : e}\n`);
+			}
+		},
+	},
+
+	remove: {
+		usage: "packed remove <name>  (bare npm name, e.g. pi-lsp or @scope/pkg)",
+		async run(_rest, d, _flags, pos) {
+			const name = pos[0] ?? "";
+			if (!NAME_RE.test(name)) return usageErr(`usage: ${commands["remove"]!.usage}\n`);
+			try {
+				return ok((await d.inst.remove(`npm:${name}`)) + "\n");
+			} catch (e) {
+				return fail(`${e instanceof Error ? e.message : e}\n`);
+			}
+		},
+	},
+
+	service: {
+		usage: "packed service  (print a systemd user unit to stdout)",
+		async run(_rest, d) {
+			const execPath = d.execPath ?? process.execPath;
+			const cliPath = d.cliPath ?? new URL("./cli.ts", import.meta.url).pathname;
+			return ok(renderUnit(execPath, cliPath));
+		},
+	},
+
+	version: {
+		usage: "packed version",
+		async run() {
+			return ok("0.1.0\n");
+		},
+	},
+};
+
+/** systemd user unit. Idle self-exit is disabled — systemd owns the
+ * lifecycle (Restart=on-failure takes over). */
+export function renderUnit(execPath: string, cliPath: string): string {
+	return `[Unit]
+Description=pi-packed package service (Pi agent)
+
+[Service]
+Type=simple
+ExecStart=${execPath} ${cliPath} serve
+Restart=on-failure
+RestartSec=2
+Environment=PI_PACKED_IDLE_SECS=0
+NoNewPrivileges=true
+
+[Install]
+WantedBy=default.target
+`;
+}
+
+export async function cliRun(args: string[], d: CliDeps): Promise<CliResult> {
+	const [name, ...rest] = args;
+	if (!name) return usageErr(USAGE);
+	if (name === "help" || name === "--help" || name === "-h") return { code: 0, out: USAGE };
+	const cmd = commands[name];
+	if (!cmd) return usageErr(`unknown command "${name}"\n${USAGE}`);
+	const { flags, pos } = parseFlags(rest);
+	try {
+		return await cmd.run(rest, d, flags, pos);
+	} catch (e) {
+		return fail(`${name} failed: ${e instanceof Error ? e.message : e}\n`);
+	}
+}
+
+// Entry point (bun src/cli.ts …). `serve` is dispatched before any proxying
+// so the daemon always talks directly to npm.
+if (import.meta.main) {
+	const args = process.argv.slice(2);
+	if (args[0] === "serve") {
+		const { serveMain } = await import("./daemon.ts");
+		serveMain();
+	} else {
+		const { stateDir } = await import("./state.ts");
+		const { defaultPiHome } = await import("./installed.ts");
+		const { resolveRegistry } = await import("./client.ts");
+		const { ExecInstaller } = await import("./install.ts");
+		const dir = stateDir();
+		const reg = await resolveRegistry(dir, "https://registry.npmjs.org");
+		const { code, out } = await cliRun(args, {
+			reg,
+			inst: new ExecInstaller(),
+			stateDir: dir,
+			piHome: defaultPiHome(),
+		});
+		process.stdout.write(out);
+		process.exit(code);
+	}
+}

package/src/client.ts

@@ -0,0 +1,80 @@
+/**
+ * client.ts — daemonRegistry: remote proxy implementing the Registry port
+ * over loopback HTTP. resolveRegistry routes CLI to the warm daemon when
+ * reachable, straight to npm otherwise.
+ */
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import type { PkgInfo, Registry, SearchPage } from "./ports.ts";
+import { HttpRegistry } from "./registry.ts";
+
+export class DaemonRegistry implements Registry {
+	constructor(
+		private base: string,
+		private token: string,
+	) {}
+
+	private async get<T>(path: string): Promise<T> {
+		const res = await fetch(`${this.base}${path}`, {
+			headers: { authorization: `Bearer ${this.token}` },
+			signal: AbortSignal.timeout(15_000),
+		});
+		if (!res.ok) throw new Error(`daemon HTTP ${res.status}`);
+		return (await res.json()) as T;
+	}
+
+	async search(query: string, limit: number): Promise<SearchPage> {
+		const body = await this.get<{ results: SearchPage["results"]; total: number }>(
+			`/search?q=${encodeURIComponent(query)}&limit=${limit}`,
+		);
+		return { results: body.results, total: body.total };
+	}
+
+	async searchPage(query: string, from: number, size: number): Promise<SearchPage> {
+		// The daemon clamps to 50; page through it for bulk reads.
+		return this.search(query, size).catch(() => ({ results: [], total: 0 }));
+	}
+
+	async searchAll(): Promise<never> {
+		// Bulk sync runs inside the daemon against the direct registry;
+		// the proxy never paginates the full universe through the clamp.
+		throw new Error("searchAll is not supported via the daemon proxy");
+	}
+
+	async info(name: string): Promise<PkgInfo> {
+		return this.get<PkgInfo>(`/info?name=${encodeURIComponent(name)}`);
+	}
+}
+
+export interface DaemonHandle {
+	base: string;
+	token: string;
+}
+
+export async function probe(dir: string): Promise<DaemonHandle | undefined> {
+	let port: string;
+	let token: string;
+	try {
+		port = readFileSync(join(dir, "port"), "utf8").trim();
+		token = readFileSync(join(dir, "token"), "utf8").trim();
+	} catch {
+		return undefined;
+	}
+	const base = `http://127.0.0.1:${port}`;
+	try {
+		const res = await fetch(`${base}/health`, {
+			headers: { authorization: `Bearer ${token}` },
+			signal: AbortSignal.timeout(800),
+		});
+		if (res.ok) return { base, token };
+	} catch {
+		/* dead daemon or stale files */
+	}
+	return undefined;
+}
+
+export async function resolveRegistry(dir: string, npmBase: string): Promise<Registry> {
+	const handle = await probe(dir);
+	if (handle) return new DaemonRegistry(handle.base, handle.token);
+	return new HttpRegistry(npmBase);
+}

package/src/daemon.ts

@@ -0,0 +1,63 @@
+/**
+ * daemon.ts — serve mode: thin wiring around tested units. Bun.serve wraps
+ * the hexagon's fetch handler; watcher + catalogSync produce snapshots;
+ * idle watchdog self-terminates (the daemon is spawned on demand).
+ */
+import { createApp } from "./service.ts";
+import { HttpRegistry } from "./registry.ts";
+import { ExecInstaller } from "./install.ts";
+import { loadOrCreateToken, writePort, idleExpired, envMs, stateDir } from "./state.ts";
+import { startWatcher } from "./watcher.ts";
+import { startCatalogSync } from "./catalog.ts";
+import { readInstalledPackages, defaultPiHome } from "./installed.ts";
+
+export function serveMain(): void {
+	const dir = stateDir();
+	const token = loadOrCreateToken(dir);
+	const reg = new HttpRegistry();
+	const app = createApp({ reg, inst: new ExecInstaller(), token, stateDir: dir });
+
+	let lastActive = Date.now();
+	const server = Bun.serve({
+		port: 0,
+		hostname: "127.0.0.1",
+		fetch: (req) => {
+			lastActive = Date.now();
+			return app.fetch(req);
+		},
+	});
+	if (!server.port) throw new Error("failed to bind listener");
+	writePort(dir, server.port);
+
+	const stopWatcher = startWatcher(reg, dir, () => readInstalledPackages(defaultPiHome()), {
+		intervalMs: envMs("PI_PACKED_WATCH_SECS", 30 * 60_000),
+	});
+	const stopCatalog = startCatalogSync(reg, dir, envMs("PI_PACKED_CATALOG_SECS", 6 * 3_600_000));
+
+	// Idle watchdog: for on-demand spawns. PI_PACKED_IDLE_SECS=0 disables it
+	// (systemd or another supervisor owns the lifecycle then).
+	const idleBudget = envMs("PI_PACKED_IDLE_SECS", 10 * 60_000);
+	let watchdog: ReturnType<typeof setInterval> | undefined;
+	if (idleBudget > 0) {
+		watchdog = setInterval(() => {
+			if (idleExpired(lastActive, Date.now(), idleBudget)) {
+				console.error(`[packed] idle for ${idleBudget / 1000}s, exiting`);
+				shutdown();
+			}
+		}, 15_000);
+	}
+
+	function shutdown(): void {
+		if (watchdog) clearInterval(watchdog);
+		stopWatcher();
+		stopCatalog();
+		server.stop(true);
+		process.exit(0);
+	}
+	process.on("SIGTERM", shutdown);
+	process.on("SIGINT", shutdown);
+
+	console.error(
+		`[packed] listening on 127.0.0.1:${server.port} (state ${dir}, watch ${envMs("PI_PACKED_WATCH_SECS", 30 * 60_000) / 1000}s, idle ${idleBudget / 1000}s)`,
+	);
+}

package/src/install.ts

@@ -0,0 +1,29 @@
+/** install.ts — driven adapter: pi CLI mutations via Bun.spawn. */
+import type { Installer } from "./ports.ts";
+
+/** Bare npm package name (for `packed remove`). */
+export const NAME_RE = /^(@[A-Za-z0-9._-]+\/)?[A-Za-z0-9._-]+$/;
+
+export class ExecInstaller implements Installer {
+	constructor(private bin = "pi") {}
+
+	private async run(args: string[]): Promise<string> {
+		const proc = Bun.spawn([this.bin, ...args], { stdout: "pipe", stderr: "pipe" });
+		const [stdout, stderr] = await Promise.all([
+			new Response(proc.stdout).text(),
+			new Response(proc.stderr).text(),
+		]);
+		const out = [stdout.trim(), stderr.trim()].filter(Boolean).join("\n");
+		const code = await proc.exited;
+		if (code !== 0) throw new Error(out || `exit ${code}`);
+		return out;
+	}
+
+	install(source: string): Promise<string> {
+		return this.run(["install", source]);
+	}
+
+	remove(source: string): Promise<string> {
+		return this.run(["remove", source]);
+	}
+}

package/src/installed.ts

@@ -0,0 +1,56 @@
+/** installed.ts — pi's settings.json is the source of truth for what is
+ * installed; node_modules supplies versions for unpinned sources. */
+import { readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import type { InstalledPkg } from "./ports.ts";
+
+export function splitNpmSource(spec: string): [name: string, version: string] {
+	const i = spec.lastIndexOf("@");
+	if (i <= 0) return [spec, ""];
+	return [spec.slice(0, i), spec.slice(i + 1)];
+}
+
+function extractSource(entry: unknown): string {
+	if (typeof entry === "string") return entry;
+	if (entry && typeof entry === "object") {
+		const s = (entry as Record<string, unknown>)["source"];
+		if (typeof s === "string") return s;
+	}
+	return "";
+}
+
+function nodeModulesVersion(piHome: string, name: string): string | undefined {
+	try {
+		const pkg = JSON.parse(readFileSync(join(piHome, "npm", "node_modules", name, "package.json"), "utf8"));
+		return typeof pkg.version === "string" ? pkg.version : undefined;
+	} catch {
+		return undefined;
+	}
+}
+
+export function readInstalledPackages(piHome: string): InstalledPkg[] {
+	let settings: { packages?: unknown[] };
+	try {
+		settings = JSON.parse(readFileSync(join(piHome, "settings.json"), "utf8"));
+	} catch {
+		return [];
+	}
+	const out: InstalledPkg[] = [];
+	for (const raw of settings.packages ?? []) {
+		const source = extractSource(raw);
+		if (!source.startsWith("npm:")) continue;
+		const [name, pinned] = splitNpmSource(source.slice(4));
+		out.push({
+			name,
+			pinned: pinned || undefined,
+			installed: pinned ? undefined : nodeModulesVersion(piHome, name),
+		});
+	}
+	return out;
+}
+
+export function defaultPiHome(): string {
+	if (process.env["PI_PACKED_PI_HOME"]) return process.env["PI_PACKED_PI_HOME"];
+	return join(homedir(), ".pi", "agent");
+}

package/src/ports.ts

@@ -0,0 +1,74 @@
+/**
+ * ports.ts — the hexagon's driven ports and lean domain types.
+ * Driving adapters: HTTP service (service.ts), CLI (cli.ts), watcher,
+ * tests. Driven adapters: registry.ts (npm), install.ts (pi exec).
+ */
+
+export interface Pkg {
+	name: string;
+	version: string;
+	description?: string;
+	date?: string;
+}
+
+export interface PkgInfo {
+	name: string;
+	version: string;
+	description?: string;
+	homepage?: string;
+	repository?: string;
+	license?: string;
+	keywords?: string[];
+	pi?: Record<string, unknown>;
+	modified?: string;
+	unpackedSize?: number;
+}
+
+export interface SearchPage {
+	results: Pkg[];
+	total: number;
+}
+
+/** Driven port: package metadata source (npm registry, or the daemon proxy). */
+export interface Registry {
+	search(query: string, limit: number): Promise<SearchPage>;
+	searchPage(query: string, from: number, size: number): Promise<SearchPage>;
+	searchAll(query: string): Promise<Pkg[]>;
+	info(name: string): Promise<PkgInfo>;
+}
+
+/** Driven port: pi CLI mutations. */
+export interface Installer {
+	install(source: string): Promise<string>;
+	remove(source: string): Promise<string>;
+}
+
+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[];
+}
+
+/** Scope every query to pi packages unless the caller already qualified it. */
+export function buildSearchQuery(q: string): string {
+	const t = q.trim();
+	if (t.includes("keywords:")) return t;
+	return t === "" ? "keywords:pi-package" : `keywords:pi-package ${t}`;
+}
+
+export function clampLimit(v: number, def: number, max: number): number {
+	if (!Number.isFinite(v) || v <= 0) return def;
+	return Math.min(v, max);
+}

package/src/registry.ts

@@ -0,0 +1,94 @@
+/**
+ * registry.ts — driven adapter: npm registry over HTTP (web-standard fetch).
+ * Lean mapping = Facade over npm's verbose package documents.
+ */
+import type { Pkg, PkgInfo, Registry, SearchPage } from "./ports.ts";
+
+export class HttpRegistry implements Registry {
+	constructor(
+		private base = "https://registry.npmjs.org",
+		private pageSize = 250,
+	) {}
+
+	async search(query: string, limit: number): Promise<SearchPage> {
+		return this.searchPage(query, 0, limit);
+	}
+
+	async searchPage(query: string, from: number, size: number): Promise<SearchPage> {
+		const params = new URLSearchParams({ text: query, size: String(size), from: String(from) });
+		const res = await fetch(`${this.base}/-/v1/search?${params}`);
+		if (!res.ok) throw new Error(`npm search: HTTP ${res.status}`);
+		const doc = (await res.json()) as {
+			total?: number;
+			objects?: { package?: { name?: string; version?: string; description?: string; date?: string } }[];
+		};
+		const results: Pkg[] = (doc.objects ?? []).flatMap((o) => {
+			const p = o.package;
+			return p?.name
+				? [{ name: p.name, version: p.version ?? "", description: p.description, date: p.date }]
+				: [];
+		});
+		return { results, total: doc.total ?? results.length };
+	}
+
+	async searchAll(query: string): Promise<Pkg[]> {
+		const out: Pkg[] = [];
+		let from = 0;
+		for (;;) {
+			const { results, total } = await this.searchPage(query, from, this.pageSize);
+			out.push(...results);
+			from += results.length;
+			if (results.length === 0 || from >= total) return out;
+		}
+	}
+
+	async info(name: string): Promise<PkgInfo> {
+		const res = await fetch(`${this.base}/${encodeURIComponent(name).replace("%2F", "/")}`, {
+			headers: { accept: "application/vnd.npm.install-v1+json" },
+		});
+		if (!res.ok) throw new Error(`npm info ${name}: HTTP ${res.status}`);
+		const doc = (await res.json()) as {
+			name?: string;
+			"dist-tags"?: Record<string, string>;
+			versions?: Record<
+				string,
+				{
+					version?: string;
+					description?: string;
+					homepage?: string;
+					license?: unknown;
+					repository?: unknown;
+					keywords?: string[];
+					pi?: Record<string, unknown>;
+					dist?: { unpackedSize?: number };
+				}
+			>;
+			time?: Record<string, string>;
+		};
+		const latest = doc["dist-tags"]?.["latest"] ?? "";
+		const v = doc.versions?.[latest];
+		if (!v) throw new Error(`npm info ${name}: version ${latest} not in document`);
+		return {
+			name: doc.name ?? name,
+			version: v.version ?? latest,
+			description: v.description,
+			homepage: v.homepage,
+			repository: rawToString(v.repository, "url"),
+			license: rawToString(v.license, "type"),
+			keywords: v.keywords,
+			pi: v.pi,
+			modified: doc.time?.["modified"],
+			unpackedSize: v.dist?.unpackedSize,
+		};
+	}
+}
+
+/** npm fields appear as plain string OR object: license: "MIT" | {type:"MIT"}. */
+function rawToString(raw: unknown, objKey: string): string | undefined {
+	if (typeof raw === "string") return raw;
+	if (raw && typeof raw === "object") {
+		const v = (raw as Record<string, unknown>)[objKey];
+		if (typeof v === "string") return v;
+	}
+	return undefined;
+}