@danypops/pi-packed 0.19.9 → 0.19.10

package/service/src/shared/atomic-json.ts

@@ -0,0 +1,33 @@
+/**
+ * packed's own atomic JSON persistence convention, layered on
+ * @danypops/vehicle-core's shared createAtomicJsonWriter: a private (0700)
+ * parent directory, refusing to overwrite a symlinked destination (defense
+ * against a symlink-swap attack on a predictable state-directory path),
+ * then the shared temp-write+rename+cleanup mechanics for the real write.
+ * Replaces 6 independent hand-rolled copies of the same
+ * writeFileSync(tmp)+renameSync dance across resources.ts, security.ts,
+ * build-index.ts, and setup.ts (twice).
+ */
+import { existsSync, lstatSync, mkdirSync } from "node:fs";
+import { dirname } from "node:path";
+import { createAtomicJsonWriter } from "@danypops/vehicle-core";
+import { createNodeAtomicJsonFsAdapter } from "@danypops/vehicle-server/atomic-json";
+
+const writer = createAtomicJsonWriter({ fs: createNodeAtomicJsonFsAdapter() });
+
+export interface WriteJsonAtomicOptions {
+	/** POSIX mode for the written file. Omitted means the OS/adapter's own default. */
+	mode?: number;
+	/** Pretty-prints with 2-space indentation. Defaults to false (compact), matching this repo's own prior per-site defaults. */
+	pretty?: boolean;
+	/** Appends a trailing newline, the convention every existing packed persistence site but writeIndex already followed. Defaults to true. */
+	trailingNewline?: boolean;
+	/** Parent directory mode, created if missing. Defaults to 0o700 (private), matching every existing packed persistence site. */
+	dirMode?: number;
+}
+
+export async function writeJsonAtomic(path: string, value: unknown, options: WriteJsonAtomicOptions = {}): Promise<void> {
+	mkdirSync(dirname(path), { recursive: true, mode: options.dirMode ?? 0o700 });
+	if (existsSync(path) && lstatSync(path).isSymbolicLink()) throw new Error(`ATOMIC_JSON_PATH_UNSAFE: refusing to replace symlink ${path}`);
+	await writer.write(path, value, { mode: options.mode, pretty: options.pretty, trailingNewline: options.trailingNewline ?? true });
+}

package/service/src/shared/cache.ts

@@ -0,0 +1,21 @@
+/** TTLCache — the smart-proxy concern, nothing more. */
+import { CACHE_TTL_MS } from "./constants.ts";
+
+export class TTLCache {
+	private m = new Map<string, { body: string; expires: number }>();
+	constructor(private ttlMs = CACHE_TTL_MS) {}
+
+	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 });
+	}
+}

package/service/src/shared/constants.ts

@@ -0,0 +1,73 @@
+/**
+ * constants.ts — every magic value in one place, named.
+ * (lexicon: replace-magic-number-with-symbolic-constant)
+ */
+
+// --- Upstream ---
+export const NPM_REGISTRY_BASE = "https://registry.npmjs.org";
+
+// --- Search / pagination ---
+export const SEARCH_DEFAULT_LIMIT = 10;
+export const SEARCH_MAX_LIMIT = 50;
+export const SEARCH_PAGE_SIZE = 250; // npm registry max page size
+export const PI_PACKAGE_KEYWORD = "keywords:pi-package";
+
+// --- Native tool presentation bounds ---
+export const TOOL_MODEL_CONTENT_MAX_CHARACTERS = 2_000;
+export const TOOL_DETAILS_MAX_SERIALIZED_CHARACTERS = 32_000;
+export const TOOL_DETAILS_MAX_PACKAGES = 50;
+export const TOOL_DETAILS_MAX_DESCRIPTION_CHARACTERS = 240;
+export const TOOL_DETAILS_MAX_OUTPUT_CHARACTERS = 1_000;
+export const TOOL_DETAILS_MAX_KEYWORDS = 20;
+export const TOOL_DETAILS_MAX_CAPABILITIES = 12;
+export const TOOL_COLLAPSED_PACKAGE_PREVIEW = 3;
+
+// --- Upstream etiquette (429s) ---
+export const RETRY_MAX_ATTEMPTS = 6;
+export const RETRY_BASE_DELAY_MS = 2_000; // 2+4+8+16+32s spans npm's ~60s search window
+export const PAGE_DELAY_MS = 100; // politeness pause between catalog pages
+export const MIRROR_PAGE_DELAY_MS = 400; // manual full-sync: extra polite (burst limits)
+
+// --- GitHub self-throttling (single-candidate commit lookup only, never bulk) ---
+// Confirmed against GitHub's own docs and @octokit/plugin-throttling's reference
+// shape: retry a short secondary-limit or transient failure, but never block an
+// interactive `packed score` call for anywhere near the full primary-limit reset
+// window (which can be up to an hour away).
+export const GITHUB_RETRY_MAX_ATTEMPTS = 4;
+export const GITHUB_MAX_TOTAL_BACKOFF_MS = 60_000; // hard cap across every retry combined
+export const GITHUB_SECONDARY_RATE_LIMIT_FALLBACK_MS = 60_000; // matches plugin-throttling's own fallbackSecondaryRateRetryAfter default when no Retry-After header is present
+export const GITHUB_TRANSIENT_BASE_DELAY_MS = 1_000; // 1+2+4s for a plain network blip or 5xx, well under the total cap
+
+// --- Cache / fetch ---
+export const CACHE_TTL_MS = 5 * 60_000;
+export const PROBE_TIMEOUT_MS = 800;
+export const REGISTRY_FETCH_TIMEOUT_MS = 15_000;
+export const MIRROR_OPERATION_TIMEOUT_MS = 2 * 60_000;
+// Confirmed live: 500 packages (index build's own bound) took just over
+// MIRROR_OPERATION_TIMEOUT_MS end to end -- a dedicated, more generous
+// budget, matching the same per-operation-timeout pattern mirror() uses.
+export const INDEX_OPERATION_TIMEOUT_MS = 10 * 60_000;
+
+// --- Daemon ---
+export const WATCH_INTERVAL_DEFAULT_MS = 30 * 60_000; // updates diff cadence
+export const CATALOG_INTERVAL_DEFAULT_MS = 6 * 3_600_000; // full mirror TTL
+export const INDEX_INTERVAL_DEFAULT_MS = 6 * 3_600_000; // static index regeneration TTL, same cadence as the catalog mirror it reads from
+export const IDLE_BUDGET_DEFAULT_MS = 10 * 60_000; // on-demand self-exit
+export const WATCHDOG_TICK_MS = 15_000;
+
+// --- State file names ---
+export const UPDATES_FILE = "updates.json";
+export const DB_FILE = "packed.db";
+export const INDEX_FILE = "index.json";
+export const SETTINGS_FILE = "settings.json";
+export const SECURITY_FILE = "security.json";
+
+// --- Environment knobs ---
+export const ENV = {
+	HOME: "PI_PACKED_HOME",
+	PI_HOME: "PI_PACKED_PI_HOME",
+	WATCH_SECS: "PI_PACKED_WATCH_SECS",
+	CATALOG_SECS: "PI_PACKED_CATALOG_SECS",
+	INDEX_SECS: "PI_PACKED_INDEX_SECS",
+	IDLE_SECS: "PI_PACKED_IDLE_SECS",
+} as const;

package/service/src/shared/log.ts

@@ -0,0 +1,21 @@
+import { createLogger as createDaemonLogger, type LogFields, type Logger, type LogLevel } from "@danypops/vehicle-server/logging";
+
+export type { LogFields, Logger, LogLevel };
+export type LogSink = (line: string) => void;
+
+/** Keeps Packed's injectable test sink while delegating level handling and serialization to vehicle-server. */
+export function createLogger(component: string, sink?: LogSink, minLevel?: LogLevel): Logger {
+	const destination = sink
+		? {
+				write(chunk: string) {
+					sink(chunk.trimEnd());
+					return true;
+				},
+			}
+		: undefined;
+	return createDaemonLogger(component, {
+		level: minLevel,
+		levelEnvVar: "PI_PACKED_LOG_LEVEL",
+		destination,
+	});
+}

package/service/src/shared/paths.ts

@@ -0,0 +1,88 @@
+import { chmodSync, copyFileSync, existsSync, mkdirSync, readFileSync, renameSync, rmSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+import { type DaemonPaths, type PathEnvironment, resolveDaemonPaths } from "@danypops/vehicle-server/paths";
+import { DB_FILE, ENV, SECURITY_FILE, SETTINGS_FILE, UPDATES_FILE } from "./constants.ts";
+
+const PATH_NAMES = {
+	stateDirectoryName: "pi-packed",
+	databaseFilename: DB_FILE,
+	tokenFilename: "token",
+	handleFilename: "handle.json",
+	systemdUnitName: "pi-packed.service",
+} as const;
+
+export interface PackedPaths extends DaemonPaths {
+	stateDirectory: string;
+}
+
+export function resolvePackedPaths(options: PathEnvironment = {}): PackedPaths {
+	const env = options.env ?? process.env;
+	const override = env[ENV.HOME];
+	if (override) {
+		const directory = resolve(override);
+		return {
+			database: join(directory, DB_FILE),
+			token: join(directory, PATH_NAMES.tokenFilename),
+			handle: join(directory, PATH_NAMES.handleFilename),
+			serviceDescriptor: join(directory, PATH_NAMES.systemdUnitName),
+			stateDirectory: directory,
+		};
+	}
+	const paths = resolveDaemonPaths(PATH_NAMES, options);
+	return { ...paths, stateDirectory: dirname(paths.token) };
+}
+
+export function legacyPackedStateDirectory(options: Pick<PathEnvironment, "env" | "home"> = {}): string {
+	const env = options.env ?? process.env;
+	const home = options.home ?? homedir();
+	return join(env.XDG_CACHE_HOME ?? join(home, ".cache"), "pi-packed");
+}
+
+function copyIfMissing(source: string, destination: string): void {
+	if (!existsSync(source) || existsSync(destination)) return;
+	mkdirSync(dirname(destination), { recursive: true, mode: 0o700 });
+	const temporary = `${destination}.${process.pid}.tmp`;
+	try {
+		copyFileSync(source, temporary);
+		chmodSync(temporary, 0o600);
+		renameSync(temporary, destination);
+	} finally {
+		rmSync(temporary, { force: true });
+	}
+}
+
+function copyDatabaseIfMissing(source: string, destination: string): void {
+	if (!existsSync(source) || existsSync(destination)) return;
+	mkdirSync(dirname(destination), { recursive: true, mode: 0o700 });
+	const temporary = `${destination}.${process.pid}.migration`;
+	const suffixes = ["", "-wal", "-shm"] as const;
+	try {
+		for (const suffix of suffixes) {
+			if (!existsSync(`${source}${suffix}`)) continue;
+			copyFileSync(`${source}${suffix}`, `${temporary}${suffix}`);
+			chmodSync(`${temporary}${suffix}`, 0o600);
+		}
+		for (const suffix of ["-shm", "-wal"] as const) {
+			if (existsSync(`${temporary}${suffix}`)) renameSync(`${temporary}${suffix}`, `${destination}${suffix}`);
+		}
+		renameSync(temporary, destination);
+	} finally {
+		for (const suffix of suffixes) rmSync(`${temporary}${suffix}`, { force: true });
+	}
+}
+
+/** Keeps existing installs usable while moving process discovery into vehicle-server's XDG split. */
+export function migrateLegacyPackedState(paths: PackedPaths, legacyDirectory = legacyPackedStateDirectory()): void {
+	if (resolve(legacyDirectory) === resolve(paths.stateDirectory)) return;
+	copyDatabaseIfMissing(join(legacyDirectory, DB_FILE), paths.database);
+	for (const filename of [SECURITY_FILE, SETTINGS_FILE, UPDATES_FILE]) {
+		copyIfMissing(join(legacyDirectory, filename), join(paths.stateDirectory, filename));
+	}
+	const legacyToken = join(legacyDirectory, PATH_NAMES.tokenFilename);
+	try {
+		if (/^[a-f0-9]{64}$/.test(readFileSync(legacyToken, "utf8").trim())) copyIfMissing(legacyToken, paths.token);
+	} catch {
+		// Old Packed tokens were 128-bit. vehicle-server intentionally rotates them to 256-bit.
+	}
+}

package/service/src/shared/state.ts

@@ -0,0 +1,15 @@
+import { resolvePackedPaths } from "./paths.ts";
+
+/** Compatibility accessor for code that stores non-database daemon state. */
+export function stateDir(): string {
+	return resolvePackedPaths().stateDirectory;
+}
+
+/** Converts a non-negative seconds environment setting to milliseconds. */
+export function envMs(key: string, defaultMs: number): number {
+	const raw = process.env[key];
+	if (raw === undefined) return defaultMs;
+	const value = Number(raw);
+	if (!Number.isFinite(value) || value < 0) return defaultMs;
+	return value * 1000;
+}

package/service/src/shared/version.ts

@@ -0,0 +1,46 @@
+import { readFileSync } from "node:fs";
+
+function packageVersion(): string {
+	const manifest = JSON.parse(readFileSync(new URL("../../../package.json", import.meta.url), "utf8")) as unknown;
+	if (typeof manifest !== "object" || manifest === null || Array.isArray(manifest)) {
+		throw new Error("packed package manifest must be an object");
+	}
+	const version = (manifest as Record<string, unknown>).version;
+	if (typeof version !== "string" || !/^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/.test(version)) {
+		throw new Error("packed package manifest has an invalid version");
+	}
+	return version;
+}
+
+/** Runtime package version; package.json is the single release source of truth. */
+export const VERSION = packageVersion();
+
+export interface VersionReport {
+	installed: string;
+	/** Undefined when no daemon is reachable at all -- not a drift concern. */
+	daemon?: { version: string; stale: boolean };
+}
+
+export function buildVersionReport(installed: string, daemonVersion: string | undefined): VersionReport {
+	return {
+		installed,
+		...(daemonVersion !== undefined ? { daemon: { version: daemonVersion, stale: daemonVersion !== installed } } : {}),
+	};
+}
+
+/** A running daemon holding stale in-memory code is otherwise invisible --
+ * it stays reachable and correctly answers every RPC, just with whatever
+ * logic was current when it started. Confirmed live: an 11-hour-old daemon
+ * kept flagging false "update available" rows from a same-day comparison
+ * fix it predated. */
+export function formatVersionReport(report: VersionReport): string {
+	const lines = [`packed ${report.installed} (installed)`];
+	if (report.daemon) {
+		lines.push(
+			report.daemon.stale
+				? `daemon running v${report.daemon.version} -- STALE, restart required to pick up v${report.installed} (e.g. systemctl --user restart pi-packed.service)`
+				: `daemon running v${report.daemon.version} -- up to date`,
+		);
+	}
+	return `${lines.join("\n")}\n`;
+}

package/service/test/advisories.test.ts

@@ -0,0 +1,287 @@
+import { afterEach, describe, expect, it } from "bun:test";
+import { mkdirSync, mkdtempSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { AuthenticatedRpcClient } from "@danypops/vehicle-client/rpc-client";
+import type { Server } from "bun";
+import { fetchBulkAdvisories, PATCHED_VERSION_FRESH_DAYS, scanInstalledPackages } from "../src/adoption/advisories.ts";
+import { createApp, type OperationInputs, type OperationName, type OperationOutputs } from "../src/daemon/service.ts";
+import type { Installer, PkgInfo, Registry, SearchPage, UpdateOutcome } from "../src/packages/package.ts";
+
+class NoopRegistry implements Registry {
+	async search(): Promise<SearchPage> {
+		return { results: [], total: 0 };
+	}
+	async searchPage(): Promise<SearchPage> {
+		return { results: [], total: 0 };
+	}
+	async searchAll() {
+		return [];
+	}
+	async info(name: string): Promise<PkgInfo> {
+		return { name, version: "1.0.0" };
+	}
+}
+
+class NoopInstaller implements Installer {
+	async install() {
+		return "ok";
+	}
+	async remove() {
+		return "ok";
+	}
+	async update(): Promise<UpdateOutcome> {
+		return { output: "ok", reloadRequired: false, alreadyUpToDate: true, pinned: false };
+	}
+}
+
+let server: Server<undefined> | undefined;
+afterEach(() => {
+	server?.stop(true);
+	server = undefined;
+});
+
+const daysAgo = (n: number) => new Date(Date.now() - n * 24 * 60 * 60 * 1000).toISOString();
+
+describe("fetchBulkAdvisories", () => {
+	it("parses a real bulk-endpoint response shape (confirmed against npm/cli's own fixture)", async () => {
+		server = Bun.serve({
+			port: 0,
+			fetch: (req) => {
+				if (req.method === "POST" && new URL(req.url).pathname === "/-/npm/v1/security/advisories/bulk") {
+					return Response.json({
+						handlebars: [
+							{
+								id: 755,
+								url: "https://npmjs.com/advisories/755",
+								title: "Prototype Pollution",
+								severity: "critical",
+								vulnerable_versions: "<=4.0.13 || >=4.1.0 <4.1.2",
+							},
+						],
+					});
+				}
+				return new Response("not found", { status: 404 });
+			},
+		});
+		const result = await fetchBulkAdvisories({ handlebars: ["4.0.5"] }, { registryBase: `http://127.0.0.1:${server.port}` });
+		expect(result).toEqual({
+			handlebars: [
+				{
+					id: 755,
+					url: "https://npmjs.com/advisories/755",
+					title: "Prototype Pollution",
+					severity: "critical",
+					vulnerableVersions: "<=4.0.13 || >=4.1.0 <4.1.2",
+				},
+			],
+		});
+	});
+
+	it("never makes a network call for an empty package set", async () => {
+		server = Bun.serve({
+			port: 0,
+			fetch: () => {
+				throw new Error("must never be called");
+			},
+		});
+		expect(await fetchBulkAdvisories({}, { registryBase: `http://127.0.0.1:${server.port}` })).toEqual({});
+	});
+
+	it("resolves to {} on a non-2xx response, never throws", async () => {
+		server = Bun.serve({ port: 0, fetch: () => new Response("nope", { status: 500 }) });
+		expect(await fetchBulkAdvisories({ foo: ["1.0.0"] }, { registryBase: `http://127.0.0.1:${server.port}` })).toEqual({});
+	});
+
+	it("resolves to {} on a malformed body, never throws", async () => {
+		server = Bun.serve({ port: 0, fetch: () => new Response("not json") });
+		expect(await fetchBulkAdvisories({ foo: ["1.0.0"] }, { registryBase: `http://127.0.0.1:${server.port}` })).toEqual({});
+	});
+
+	it("resolves to {} on an unreachable host, never throws or hangs", async () => {
+		expect(await fetchBulkAdvisories({ foo: ["1.0.0"] }, { registryBase: "http://127.0.0.1:1", timeoutMs: 500 })).toEqual({});
+	});
+
+	it("defaults an unrecognized severity to high rather than dropping the advisory", async () => {
+		server = Bun.serve({ port: 0, fetch: () => Response.json({ foo: [{ id: 1, url: "u", title: "t", vulnerable_versions: "*" }] }) });
+		const result = await fetchBulkAdvisories({ foo: ["1.0.0"] }, { registryBase: `http://127.0.0.1:${server.port}` });
+		expect(result.foo?.[0]?.severity).toBe("high");
+	});
+});
+
+describe("scanInstalledPackages", () => {
+	function fixtureServer(handlers: { bulk?: unknown; packument?: (name: string) => unknown }): Server<undefined> {
+		return Bun.serve({
+			port: 0,
+			fetch: (req) => {
+				const url = new URL(req.url);
+				if (req.method === "POST" && url.pathname === "/-/npm/v1/security/advisories/bulk") return Response.json(handlers.bulk ?? {});
+				const name = decodeURIComponent(url.pathname.slice(1));
+				if (handlers.packument) return Response.json(handlers.packument(name));
+				return new Response("not found", { status: 404 });
+			},
+		});
+	}
+
+	it("computes patched-version-age as a fresh signal for a very recently published fix", async () => {
+		server = fixtureServer({
+			bulk: {
+				"pi-demo": [
+					{ id: 1, url: "https://example.test/1", title: "Prototype Pollution", severity: "high", vulnerable_versions: "<2.0.0" },
+				],
+			},
+			packument: () => ({
+				versions: { "1.0.0": {}, "2.0.0": {}, "2.0.1": {} },
+				time: { "1.0.0": daysAgo(400), "2.0.0": daysAgo(2), "2.0.1": daysAgo(1) },
+			}),
+		});
+		const report = await scanInstalledPackages({ "pi-demo": "1.0.0" }, { registryBase: `http://127.0.0.1:${server.port}` });
+		expect(report.findings).toHaveLength(1);
+		const finding = report.findings[0]!;
+		expect(finding.patchedVersionAge?.version).toBe("2.0.0"); // smallest version outside the vulnerable range
+		expect(finding.patchedVersionAge?.fresh).toBe(true);
+		expect(finding.patchedVersionAge?.ageDays).toBeLessThan(PATCHED_VERSION_FRESH_DAYS);
+	});
+
+	it("reports fresh:false for a fix that has aged past the threshold", async () => {
+		// computed once, reused in both the fixture and the assertion -- a
+		// wall-clock ISO string recomputed on each side of an async boundary
+		// can differ by a millisecond and make an exact-equality assertion
+		// flaky under real scheduling, independent of the implementation.
+		const publishedAt = daysAgo(365);
+		server = fixtureServer({
+			bulk: { "pi-demo": [{ id: 1, url: "u", title: "t", severity: "high", vulnerable_versions: "<2.0.0" }] },
+			packument: () => ({ versions: { "1.0.0": {}, "2.0.0": {} }, time: { "1.0.0": daysAgo(400), "2.0.0": publishedAt } }),
+		});
+		const report = await scanInstalledPackages({ "pi-demo": "1.0.0" }, { registryBase: `http://127.0.0.1:${server.port}` });
+		expect(report.findings[0]!.patchedVersionAge).toEqual({ version: "2.0.0", publishedAt, ageDays: 365, fresh: false });
+	});
+
+	it("never guesses a patched version when nothing published escapes the vulnerable range", async () => {
+		server = fixtureServer({
+			bulk: { "pi-demo": [{ id: 1, url: "u", title: "t", severity: "high", vulnerable_versions: "*" }] },
+			packument: () => ({ versions: { "1.0.0": {} }, time: { "1.0.0": daysAgo(10) } }),
+		});
+		const report = await scanInstalledPackages({ "pi-demo": "1.0.0" }, { registryBase: `http://127.0.0.1:${server.port}` });
+		expect(report.findings[0]!.patchedVersionAge).toBeUndefined();
+		expect(report.diagnostics[0]!.fix).toBeUndefined();
+	});
+
+	it("maps advisory severity to diagnostic severity independent of patched-version freshness -- never folds one into the other", async () => {
+		server = fixtureServer({
+			bulk: {
+				"fresh-critical": [{ id: 1, url: "u", title: "t", severity: "critical", vulnerable_versions: "<2.0.0" }],
+				"old-critical": [{ id: 2, url: "u", title: "t", severity: "critical", vulnerable_versions: "<2.0.0" }],
+			},
+			packument: (name) =>
+				name === "fresh-critical"
+					? { versions: { "1.0.0": {}, "2.0.0": {} }, time: { "1.0.0": daysAgo(400), "2.0.0": daysAgo(1) } }
+					: { versions: { "1.0.0": {}, "2.0.0": {} }, time: { "1.0.0": daysAgo(400), "2.0.0": daysAgo(900) } },
+		});
+		const report = await scanInstalledPackages(
+			{ "fresh-critical": "1.0.0", "old-critical": "1.0.0" },
+			{ registryBase: `http://127.0.0.1:${server.port}` },
+		);
+		const fresh = report.diagnostics.find((d) => d.path === "fresh-critical")!;
+		const old = report.diagnostics.find((d) => d.path === "old-critical")!;
+		expect(fresh.severity).toBe("error");
+		expect(old.severity).toBe("error"); // same severity as fresh -- freshness never changes it
+		expect(fresh.message).toContain("weaker signal");
+		expect(old.message).not.toContain("weaker signal");
+	});
+
+	it("maps moderate to warning and low to info", async () => {
+		server = fixtureServer({
+			bulk: {
+				pkga: [{ id: 1, url: "u", title: "t", severity: "moderate", vulnerable_versions: "*" }],
+				pkgb: [{ id: 2, url: "u", title: "t", severity: "low", vulnerable_versions: "*" }],
+			},
+		});
+		const report = await scanInstalledPackages({ pkga: "1.0.0", pkgb: "1.0.0" }, { registryBase: `http://127.0.0.1:${server.port}` });
+		expect(report.diagnostics.find((d) => d.path === "pkga")!.severity).toBe("warning");
+		expect(report.diagnostics.find((d) => d.path === "pkgb")!.severity).toBe("info");
+	});
+
+	it("reports zero findings for a package with no advisories", async () => {
+		server = fixtureServer({ bulk: {} });
+		const report = await scanInstalledPackages({ "pi-demo": "1.0.0" }, { registryBase: `http://127.0.0.1:${server.port}` });
+		expect(report.findings).toEqual([]);
+		expect(report.diagnostics).toEqual([]);
+		expect(report.scanned).toBe(1);
+	});
+
+	it("never executes package code -- scanning is pure metadata comparison", async () => {
+		// no eval/require/child_process anywhere in the module; structural
+		// guarantee, not just an assertion about this one test run
+		const source = await Bun.file(new URL("../src/adoption/advisories.ts", import.meta.url)).text();
+		expect(source).not.toMatch(/\brequire\(|child_process|Bun\.spawn|eval\(/);
+	});
+});
+
+describe("advisories.scan operation (real daemon route)", () => {
+	it("resolves real installed npm packages' on-disk versions and routes through the authenticated operation registry", async () => {
+		const piHome = mkdtempSync(join(tmpdir(), "packed-advisories-daemon-"));
+		writeFileSync(join(piHome, "settings.json"), JSON.stringify({ packages: ["npm:pi-vuln"] }));
+		const pkgDir = join(piHome, "npm", "node_modules", "pi-vuln");
+		mkdirSync(pkgDir, { recursive: true });
+		writeFileSync(join(pkgDir, "package.json"), JSON.stringify({ name: "pi-vuln", version: "1.0.0" }));
+
+		let receivedInstalled: Record<string, string> | undefined;
+		const app = createApp({
+			reg: new NoopRegistry(),
+			inst: new NoopInstaller(),
+			token: "test-token",
+			stateDir: mkdtempSync(join(tmpdir(), "packed-advisories-state-")),
+			dataDir: mkdtempSync(join(tmpdir(), "packed-advisories-data-")),
+			piHome,
+			// injected exactly like pi.status's piVersion seam -- never a real
+			// network call to the live npm registry from an automated test.
+			advisories: {
+				async scan(installed) {
+					receivedInstalled = installed;
+					return { scanned: Object.keys(installed).length, findings: [], diagnostics: [], truncated: false };
+				},
+			},
+		});
+		const client = new AuthenticatedRpcClient<OperationName, OperationInputs, OperationOutputs>("http://packed.test", "test-token", {
+			label: "Packed",
+			transport: (request) => app.fetch(request),
+		});
+		expect(await client.operations()).toContain("advisories.scan");
+		const report = await client.call("advisories.scan", {});
+		expect(report.scanned).toBe(1);
+		expect(receivedInstalled).toEqual({ "pi-vuln": "1.0.0" }); // real on-disk resolution, not a guess
+	});
+
+	it("is unguarded read access -- never requires approval", async () => {
+		const app = createApp({
+			reg: new NoopRegistry(),
+			inst: new NoopInstaller(),
+			token: "test-token",
+			stateDir: mkdtempSync(join(tmpdir(), "packed-advisories-state-")),
+			dataDir: mkdtempSync(join(tmpdir(), "packed-advisories-data-")),
+			piHome: mkdtempSync(join(tmpdir(), "packed-advisories-pihome-")),
+		});
+		const client = new AuthenticatedRpcClient<OperationName, OperationInputs, OperationOutputs>("http://packed.test", "test-token", {
+			label: "Packed",
+			transport: (request) => app.fetch(request),
+		});
+		expect(await client.call("advisories.scan", {})).toEqual({ scanned: 0, findings: [], diagnostics: [], truncated: false });
+	});
+
+	it("rejects an oversized name argument rather than passing it through", async () => {
+		const app = createApp({
+			reg: new NoopRegistry(),
+			inst: new NoopInstaller(),
+			token: "test-token",
+			stateDir: mkdtempSync(join(tmpdir(), "packed-advisories-state-")),
+			dataDir: mkdtempSync(join(tmpdir(), "packed-advisories-data-")),
+			piHome: mkdtempSync(join(tmpdir(), "packed-advisories-pihome-")),
+		});
+		const client = new AuthenticatedRpcClient<OperationName, OperationInputs, OperationOutputs>("http://packed.test", "test-token", {
+			label: "Packed",
+			transport: (request) => app.fetch(request),
+		});
+		await expect(client.call("advisories.scan", { name: "x".repeat(300) })).rejects.toThrow();
+	});
+});