@danypops/pi-packed 0.2.0 → 0.2.1

package/README.md

@@ -1,92 +1,114 @@
 # pi-packed
 
-Package service for the [Pi](https://github.com/earendil-works/pi-coding-agent) agent —
+Package service for the [Pi](https://github.com/earendil-works/pi) 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│          │
-└───────────────────────────────────────────────┴──────────┘
+The agent gets native tools (`pkg_search`, `pkg_info`, `pkg_install`); you get
+the `packed` CLI and an interactive `/packages` TUI. The extension is a thin,
+Node-compatible client. Registry access, SQLite, and package execution remain
+inside the supervised Bun daemon.
+
+```text
+┌─ Pi extension (Node-compatible) ──────────────┐
+│ pkg_search · pkg_info · pkg_install           │
+│ /packages · session_start update notification │
+│ confirmation gates · no Bun/SQLite dependency │
+└──────────────────┬────────────────────────────┘
+                   │ authenticated loopback HTTP
+┌─ packed.service (Bun) ────────────────────────┐
+│ typed package client API · watcher · mirror   │
+│ npm registry · SQLite WAL · pi install/remove │
+└───────────────────────────────────────────────┘
 ```
 
 ## 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
+bun test
+packed service > ~/.config/systemd/user/packed.service
+systemctl --user daemon-reload
+systemctl --user enable --now packed.service
+
+packed search lsp
+packed install npm:pi-lsp
+packed installed --json
+
+# In Pi after installing the package:
+/packages
 ```
 
+Packages execute arbitrary code. `pkg_install` always requires interactive user
+confirmation before the extension sends the mutation to the authenticated
+daemon.
+
 ## 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)
+| `packed search <q> [--offline] [--limit N] [--json]` | Search npm or the local mirror, scoped to `keywords:pi-package` |
+| `packed info <name> [--json]` | Show version, repository, Pi manifest, size, and license |
+| `packed updates [--json]` | Show drift from the local mirror |
+| `packed mirror [--json]` | Refresh the SQLite package index |
+| `packed installed [--json]` | Read Pi's installed package declarations |
+| `packed catalog [--json]` | Inspect the local package index |
+| `packed install <source> [--json]` | Authenticated daemon install for `npm:`, `git:`, or `https://` sources |
+| `packed remove <name> [--json]` | Authenticated daemon removal by bare npm name |
+| `packed serve` | Run the loopback daemon |
+| `packed service` | Print the systemd user unit |
+| `packed version` | Print the package/service version |
+
+Install/remove JSON results are stable objects:
+
+```json
+{"ok":true,"source":"npm:pi-lsp","output":"Installed npm:pi-lsp"}
+```
 
-`GET /health` · `GET /search?q=&limit=` · `GET /info?name=` · `POST /install`
-· `GET /updates` · `GET /catalog`
+Failures use exit code 1 and `{ "ok": false, ... , "error": "..." }` with
+credential-safe diagnostics. Usage errors use exit code 2.
 
-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).
+## Service API
 
-## Architecture (patterns)
+Every route requires the bearer token stored in the private state directory.
+The daemon listens on loopback only.
 
-| Pattern | Where |
+| Method | Route |
 |---|---|
-| 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`
+| `GET` | `/health` |
+| `GET` | `/search?q=&limit=&offline=1` |
+| `GET` | `/info?name=` |
+| `GET` | `/installed` |
+| `GET` | `/updates` |
+| `GET` | `/catalog` |
+| `POST` | `/install` with `{ "source": "..." }` |
+| `POST` | `/remove` with `{ "name": "..." }` |
+
+State defaults to `~/.cache/pi-packed/` and contains `token`, `port`,
+`updates.json`, and `packed.db`. Relevant environment variables:
+
+- `PI_PACKED_HOME`
+- `PI_PACKED_PI_HOME`
+- `PI_PACKED_WATCH_SECS`
+- `PI_PACKED_CATALOG_SECS`
+- `PI_PACKED_IDLE_SECS`
+- `PI_PACKED_PI_BIN` / `PI_BIN`
+
+## Architecture and safety
+
+- **Daemon-owned SQLite:** extensions never open the mirror directly.
+- **Runtime boundary:** extensions never call `Bun.spawn`; only the supervised
+  Bun daemon owns the `ExecInstaller` adapter.
+- **Authenticated typed client:** extension and mutation CLI paths call the same
+  loopback API and reconnect after daemon restarts.
+- **Ports and adapters:** registry and installer ports keep policy independent
+  from npm, SQLite, subprocess, HTTP, and UI adapters.
+- **Allowlisted mutation input:** package sources and names reject shell
+  metacharacters before reaching the installer.
+- **Bounded requests:** daemon calls use timeouts and return structured errors
+  without tokens or credentials.
+
+## Development
+
+```bash
+bun test
+bunx tsc --noEmit
+```

package/extension/src/index.ts

@@ -14,8 +14,8 @@ import { showPackages } from "./tui.js";
 import { createNatives } from "./packed.js";
 import { formatUpdateNotice } from "./model.js";
 
-// Async factory (pi awaits it): dynamic imports load the service library
-// in-process — the native pattern, no subprocess.
+// Async factory (pi awaits it): the seam creates authenticated daemon
+// clients lazily. It never executes Bun-only adapters or opens SQLite.
 export default async function (pi: ExtensionAPI) {
 	const natives = await createNatives();
 	registerTools(pi, natives);

package/extension/src/packed.ts

@@ -1,17 +1,18 @@
 /**
- * packed.ts — native library client. The seam imports the pi-packed service
- * modules IN-PROCESS (web-spider's pattern: dynamic import() bypasses jiti's
- * CJS interop, which can drop class constructors for "type":"module" packages).
+ * packed.ts — thin Pi extension seam over the authenticated package daemon.
  *
- * The SQLite mirror is the shared substrate (WAL: the daemon writes, we read
- * concurrently). The daemon remains the background producer; the seam works
- * even with the daemon down. No subprocess, no token/port files.
+ * Pi's extension runtime is Node-compatible and does not guarantee a global
+ * `Bun`. All registry reads, SQLite access, and package mutations therefore
+ * stay inside the supervised Bun daemon. The seam reconnects for every call so
+ * a restarted daemon cannot leave a stale port/token client cached in Pi.
  */
-import type { Db } from "../../src/db.ts";
+import type { PackageDaemonPort as ClientPackageDaemonPort } from "../../src/client.ts";
 import type { InstalledPkg, Pkg, PkgInfo, UpdateEntry } from "../../src/ports.ts";
 
 export type { InstalledPkg, UpdateEntry };
 export type PackageInfo = PkgInfo;
+export type PackageDaemonPort = ClientPackageDaemonPort;
+
 export interface SearchResponse {
 	query: string;
 	total: number;
@@ -28,52 +29,36 @@ export interface Natives {
 	remove(name: string): Promise<string>;
 }
 
-export async function createNatives(): Promise<Natives> {
-	const [dbMod, regMod, instMod, watchMod, execMod, stateMod, portsMod] = await Promise.all([
-		import("../../src/db.ts"),
-		import("../../src/registry.ts"),
-		import("../../src/installed.ts"),
-		import("../../src/watcher.ts"),
-		import("../../src/install.ts"),
+export type PackageDaemonConnector = () => Promise<PackageDaemonPort>;
+
+async function connectDefaultDaemon(): Promise<PackageDaemonPort> {
+	const [client, state] = await Promise.all([
+		import("../../src/client.ts"),
 		import("../../src/state.ts"),
-		import("../../src/ports.ts"),
 	]);
+	return client.connectPackageDaemon(state.stateDir());
+}
 
-	const reg = new regMod.HttpRegistry();
-	const inst = new execMod.ExecInstaller();
-
-	// Per-call open/close: lifecycle-clean (no held handles, safe with the
-	// daemon writing concurrently under WAL).
-	function withDb<T>(fn: (db: Db) => T): T {
-		const db = dbMod.openDb(dbMod.dbPath(stateMod.stateDir()));
-		try {
-			return fn(db);
-		} finally {
-			db.close();
+export async function createNatives(connect: PackageDaemonConnector = connectDefaultDaemon): Promise<Natives> {
+	async function call<T>(operation: (daemon: PackageDaemonPort) => Promise<T>): Promise<T> {
+		let lastError: unknown;
+		for (let attempt = 0; attempt < 2; attempt += 1) {
+			try {
+				return await operation(await connect());
+			} catch (error) {
+				lastError = error;
+			}
 		}
+		throw lastError instanceof Error ? lastError : new Error(String(lastError));
 	}
 
 	return {
-		async search(query, limit) {
-			const { results, total } = await reg.search(portsMod.buildSearchQuery(query), limit);
-			return { query, total, results };
-		},
-		async searchOffline(query, limit) {
-			const results = withDb((db) => dbMod.searchLocal(db, query, limit));
-			return { query, total: results.length, results };
-		},
-		info: (name) => reg.info(name),
-		installed: () => Promise.resolve(instMod.readInstalledPackages(instMod.defaultPiHome())),
-		updates: () =>
-			Promise.resolve(
-				withDb((db) =>
-					watchMod.checkUpdates(
-						(name) => dbMod.latestVersion(db, name),
-						instMod.readInstalledPackages(instMod.defaultPiHome()),
-					),
-				),
-			),
-		install: (source) => inst.install(source),
-		remove: (name) => inst.remove(`npm:${name}`),
+		search: (query, limit) => call((daemon) => daemon.search(query, limit)),
+		searchOffline: (query, limit) => call((daemon) => daemon.search(query, limit, true)),
+		info: (name) => call((daemon) => daemon.info(name)),
+		installed: () => call((daemon) => daemon.installed()),
+		updates: () => call((daemon) => daemon.updates()),
+		install: (source) => call((daemon) => daemon.install(source)),
+		remove: (name) => call((daemon) => daemon.remove(name)),
 	};
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@danypops/pi-packed",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "Package service for the Pi agent: search/info/install/updates + /packages TUI, backed by a long-running Bun service",
   "type": "module",
   "keywords": [
@@ -8,6 +8,7 @@
   ],
   "scripts": {
     "test": "bun test",
+    "typecheck": "bun x tsc --noEmit",
     "cli": "bun src/cli.ts",
     "serve": "bun src/cli.ts serve"
   },

package/src/cli.ts

@@ -10,7 +10,12 @@ import { readInstalledPackages } from "./installed.ts";
 import { checkUpdates } from "./watcher.ts";
 import { syncCatalog } from "./catalog.ts";
 import { openDb, searchLocal, catalogList, getSyncMeta, latestVersion, dbPath } from "./db.ts";
-import { NAME_RE } from "./install.ts";
+import { NAME_RE, defaultPiBin } from "./install.ts";
+
+function defaultPiBinForUnit(): string | undefined {
+	const b = defaultPiBin();
+	return b === "pi" ? undefined : b; // bare name needs no pin
+}
 import {
 	VERSION, SEARCH_DEFAULT_LIMIT, SEARCH_MAX_LIMIT, NPM_REGISTRY_BASE, SEARCH_PAGE_SIZE, MIRROR_PAGE_DELAY_MS,
 } from "./constants.ts";
@@ -26,8 +31,8 @@ usage:
   packed mirror [--json]                       sync upstream into the local SQLite index
   packed installed [--json]                    installed pi packages
   packed catalog [--json]                      local package index (apt-cache stats)
-  packed install <source>                      pi install npm:|git:|https://…
-  packed remove <name>                         remove by bare npm name
+  packed install <source> [--json]             pi install npm:|git:|https://… via daemon
+  packed remove <name> [--json]                remove by bare npm name via daemon
   packed serve                                 run the long-running daemon
   packed service                               print a systemd user unit
   packed version                               print version
@@ -40,6 +45,7 @@ export interface CliDeps {
 	piHome: string;
 	execPath?: string; // bun binary (defaults to process.execPath)
 	cliPath?: string; // this CLI's entry file (for the systemd unit)
+	piBin?: string; // pi binary path to pin into the unit's Environment
 }
 
 export interface CliResult {
@@ -179,27 +185,31 @@ const commands: Record<string, { usage: string; run: Command }> = {
 	},
 
 	install: {
-		usage: "packed install npm:<pkg>[@ver] | git:<host>/<owner>/<repo>[@ref] | https://…",
-		async run(_rest, d, _flags, pos) {
+		usage: "packed install npm:<pkg>[@ver] | git:<host>/<owner>/<repo>[@ref] | https://… [--json]",
+		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");
+				const output = await d.inst.install(source);
+				return flags.json ? ok(`${JSON.stringify({ ok: true, source, output })}\n`) : ok(`${output}\n`);
 			} catch (e) {
-				return fail(`${e instanceof Error ? e.message : e}\n`);
+				const error = e instanceof Error ? e.message : String(e);
+				return flags.json ? fail(`${JSON.stringify({ ok: false, source, error })}\n`) : fail(`${error}\n`);
 			}
 		},
 	},
 
 	remove: {
-		usage: "packed remove <name>  (bare npm name, e.g. pi-lsp or @scope/pkg)",
-		async run(_rest, d, _flags, pos) {
+		usage: "packed remove <name> [--json]  (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");
+				const output = await d.inst.remove(`npm:${name}`);
+				return flags.json ? ok(`${JSON.stringify({ ok: true, name, output })}\n`) : ok(`${output}\n`);
 			} catch (e) {
-				return fail(`${e instanceof Error ? e.message : e}\n`);
+				const error = e instanceof Error ? e.message : String(e);
+				return flags.json ? fail(`${JSON.stringify({ ok: false, name, error })}\n`) : fail(`${error}\n`);
 			}
 		},
 	},
@@ -209,7 +219,7 @@ const commands: Record<string, { usage: string; run: Command }> = {
 		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));
+			return ok(renderUnit(execPath, cliPath, d.piBin ?? defaultPiBinForUnit()));
 		},
 	},
 
@@ -223,7 +233,10 @@ const commands: Record<string, { usage: string; run: Command }> = {
 
 /** 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 {
+export function renderUnit(execPath: string, cliPath: string, piBin?: string): string {
+	// systemd does not read shell rc files: PI_BIN must be explicit so the
+	// daemon's install/remove execs can find the pi binary.
+	const piEnv = piBin ? `Environment=PI_BIN=${piBin}\n` : "";
 	return `[Unit]
 Description=pi-packed package service (Pi agent)
 
@@ -233,7 +246,7 @@ ExecStart=${execPath} ${cliPath} serve
 Restart=on-failure
 RestartSec=2
 Environment=PI_PACKED_IDLE_SECS=0
-NoNewPrivileges=true
+${piEnv}NoNewPrivileges=true
 
 [Install]
 WantedBy=default.target
@@ -264,8 +277,7 @@ if (import.meta.main) {
 	} 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 { DaemonBackedInstaller, resolveRegistry } = await import("./client.ts");
 		const dir = stateDir();
 		// mirror talks to UPSTREAM, not the daemon cache — apt update semantics.
 		const reg =
@@ -274,7 +286,7 @@ if (import.meta.main) {
 				: await resolveRegistry(dir, NPM_REGISTRY_BASE);
 		const { code, out } = await cliRun(args, {
 			reg,
-			inst: new ExecInstaller(),
+			inst: new DaemonBackedInstaller(dir),
 			stateDir: dir,
 			piHome: defaultPiHome(),
 		});

package/src/client.ts

@@ -1,49 +1,158 @@
 /**
- * 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.
+ * client.ts — authenticated loopback clients for the supervised package daemon.
+ * The CLI may fall back to npm for read-only registry queries; Pi extensions use
+ * PackageDaemonClient exclusively so Bun execution and SQLite remain daemon-owned.
  */
 import { readFileSync } from "node:fs";
 import { join } from "node:path";
-import type { PkgInfo, Registry, SearchPage } from "./ports.ts";
+import type { InstalledPkg, Installer, PkgInfo, Registry, SearchPage, UpdateEntry, UpdatesSnapshot } from "./ports.ts";
 import { HttpRegistry } from "./registry.ts";
 import { DAEMON_HOST, PROBE_TIMEOUT_MS, REGISTRY_FETCH_TIMEOUT_MS, PORT_FILE, TOKEN_FILE } from "./constants.ts";
 
-export class DaemonRegistry implements Registry {
+export type FetchTransport = (request: Request) => Promise<Response>;
+
+export interface PackageDaemonPort {
+	search(query: string, limit: number, offline?: boolean): Promise<{ query: string; total: number; results: SearchPage["results"] }>;
+	info(name: string): Promise<PkgInfo>;
+	installed(): Promise<InstalledPkg[]>;
+	updates(): Promise<UpdateEntry[]>;
+	install(source: string): Promise<string>;
+	remove(name: string): Promise<string>;
+}
+
+interface MutationResponse {
+	ok: boolean;
+	output: string;
+}
+
+export class PackageDaemonError extends Error {
 	constructor(
-		private base: string,
-		private token: string,
+		message: string,
+		readonly operation: string,
+		readonly status?: number,
+	) {
+		super(message);
+		this.name = "PackageDaemonError";
+	}
+}
+
+export class PackageDaemonClient implements PackageDaemonPort {
+	constructor(
+		private readonly base: string,
+		private readonly token: string,
+		private readonly transport: FetchTransport = fetch,
 	) {}
 
-	private async get<T>(path: string): Promise<T> {
-		const res = await fetch(`${this.base}${path}`, {
-			headers: { authorization: `Bearer ${this.token}` },
-			signal: AbortSignal.timeout(REGISTRY_FETCH_TIMEOUT_MS),
+	private async request<T>(path: string, init: RequestInit = {}): Promise<T> {
+		const headers = new Headers(init.headers);
+		headers.set("authorization", `Bearer ${this.token}`);
+		if (init.body !== undefined) headers.set("content-type", "application/json");
+		const response = await this.transport(new Request(`${this.base}${path}`, {
+			...init,
+			headers,
+			signal: init.signal ?? AbortSignal.timeout(REGISTRY_FETCH_TIMEOUT_MS),
+		}));
+		let body: unknown;
+		try {
+			body = await response.json();
+		} catch {
+			throw new PackageDaemonError(`package daemon returned invalid JSON (HTTP ${response.status})`, path, response.status);
+		}
+		if (!response.ok) {
+			const message = typeof body === "object" && body !== null && typeof (body as { error?: unknown }).error === "string"
+				? (body as { error: string }).error
+				: `package daemon HTTP ${response.status}`;
+			throw new PackageDaemonError(message, path, response.status);
+		}
+		return body as T;
+	}
+
+	async search(query: string, limit: number, offline = false): Promise<{ query: string; total: number; results: SearchPage["results"] }> {
+		const params = new URLSearchParams({ q: query, limit: String(limit) });
+		if (offline) params.set("offline", "1");
+		return this.request(`/search?${params}`);
+	}
+
+	info(name: string): Promise<PkgInfo> {
+		return this.request(`/info?name=${encodeURIComponent(name)}`);
+	}
+
+	installed(): Promise<InstalledPkg[]> {
+		return this.request("/installed");
+	}
+
+	async updates(): Promise<UpdateEntry[]> {
+		return (await this.request<UpdatesSnapshot>("/updates")).updates;
+	}
+
+	async install(source: string): Promise<string> {
+		const result = await this.request<MutationResponse>("/install", {
+			method: "POST",
+			body: JSON.stringify({ source }),
 		});
-		if (!res.ok) throw new Error(`daemon HTTP ${res.status}`);
-		return (await res.json()) as T;
+		if (!result.ok) throw new PackageDaemonError(result.output || `failed to install ${source}`, "install");
+		return result.output;
+	}
+
+	async remove(name: string): Promise<string> {
+		const result = await this.request<MutationResponse>("/remove", {
+			method: "POST",
+			body: JSON.stringify({ name }),
+		});
+		if (!result.ok) throw new PackageDaemonError(result.output || `failed to remove ${name}`, "remove");
+		return result.output;
+	}
+}
+
+export class PackageDaemonInstaller implements Installer {
+	constructor(private readonly client: PackageDaemonClient) {}
+
+	install(source: string): Promise<string> {
+		return this.client.install(source);
+	}
+
+	remove(source: string): Promise<string> {
+		if (!source.startsWith("npm:") || source.length <= 4) {
+			throw new PackageDaemonError("daemon package removal requires an npm: source", "remove");
+		}
+		return this.client.remove(source.slice(4));
+	}
+}
+
+export class DaemonBackedInstaller implements Installer {
+	constructor(private readonly stateDirectory: string) {}
+
+	async install(source: string): Promise<string> {
+		return (await connectPackageDaemon(this.stateDirectory)).install(source);
+	}
+
+	async remove(source: string): Promise<string> {
+		return new PackageDaemonInstaller(await connectPackageDaemon(this.stateDirectory)).remove(source);
+	}
+}
+
+export class DaemonRegistry implements Registry {
+	private readonly client: PackageDaemonClient;
+
+	constructor(base: string, token: string, transport: FetchTransport = fetch) {
+		this.client = new PackageDaemonClient(base, token, transport);
 	}
 
 	async search(query: string, limit: number): Promise<SearchPage> {
-		const body = await this.get<{ results: SearchPage["results"]; total: number }>(
-			`/search?q=${encodeURIComponent(query)}&limit=${limit}`,
-		);
+		const body = await this.client.search(query, 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.
+	async searchPage(query: string, _from: number, size: number): Promise<SearchPage> {
 		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)}`);
+	info(name: string): Promise<PkgInfo> {
+		return this.client.info(name);
 	}
 }
 
@@ -74,6 +183,12 @@ export async function probe(dir: string): Promise<DaemonHandle | undefined> {
 	return undefined;
 }
 
+export async function connectPackageDaemon(dir: string): Promise<PackageDaemonClient> {
+	const handle = await probe(dir);
+	if (!handle) throw new Error("pi-packed daemon is unavailable; start packed.service");
+	return new PackageDaemonClient(handle.base, handle.token);
+}
+
 export async function resolveRegistry(dir: string, npmBase: string): Promise<Registry> {
 	const handle = await probe(dir);
 	if (handle) return new DaemonRegistry(handle.base, handle.token);

package/src/constants.ts

@@ -31,7 +31,7 @@ export const IDLE_BUDGET_DEFAULT_MS = 10 * 60_000; // on-demand self-exit
 export const WATCHDOG_TICK_MS = 15_000;
 
 // --- Identity ---
-export const VERSION = "0.1.0";
+export const VERSION = "0.2.1";
 
 // --- State-dir file names ---
 export const TOKEN_FILE = "token";

package/src/install.ts

@@ -4,8 +4,12 @@ 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 function defaultPiBin(): string {
+	return process.env["PI_PACKED_PI_BIN"] ?? process.env["PI_BIN"] ?? "pi";
+}
+
 export class ExecInstaller implements Installer {
-	constructor(private bin = "pi") {}
+	constructor(private bin = defaultPiBin()) {}
 
 	private async run(args: string[]): Promise<string> {
 		const proc = Bun.spawn([this.bin, ...args], { stdout: "pipe", stderr: "pipe" });