@danypops/pi-packed 0.19.7 → 0.19.10

package/service/src/daemon/watcher.ts

@@ -0,0 +1,92 @@
+/**
+ * watcher.ts — event producer #1: version-drift detection.
+ * Diffs installed packages against registry dist-tags.latest and persists
+ * an event snapshot (event-carried state) for cheap consumer reads.
+ */
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { gt, valid } from "semver";
+import { UPDATES_FILE } from "../shared/constants.ts";
+import { createLogger } from "../shared/log.ts";
+
+const log = createLogger("watcher");
+
+import type { InstalledPkg, UpdateEntry, UpdatesSnapshot } from "../packages/package.ts";
+
+function updatesPath(dir: string): string {
+	return join(dir, UPDATES_FILE);
+}
+
+export async function saveUpdates(dir: string, snap: UpdatesSnapshot): Promise<void> {
+	await mkdir(dir, { recursive: true });
+	await writeFile(updatesPath(dir), JSON.stringify(snap), { mode: 0o600 });
+}
+
+export async function loadUpdates(dir: string): Promise<UpdatesSnapshot | undefined> {
+	try {
+		return JSON.parse(await readFile(updatesPath(dir), "utf8")) as UpdatesSnapshot;
+	} catch {
+		return undefined;
+	}
+}
+
+/**
+ * True drift only: mirrored latest is a real semver step *ahead* of what's
+ * installed, never merely different from it. A plain !== check (this
+ * function's own bug until fixed) cannot distinguish "installed is behind
+ * latest" from "installed is already ahead of a stale/wrong mirrored
+ * latest" -- confirmed live: an installed package whose version had
+ * already passed the daemon's own mirrored dist-tags.latest kept showing
+ * a permanent, un-clearable "update available" badge pointing at an
+ * *older* version. Falls back to the old inequality only when either side
+ * isn't parseable semver (a git ref, a literal "latest" tag, etc.) --
+ * those aren't comparable at all, so "different" is the only signal left.
+ */
+function isNewer(latest: string, have: string): boolean {
+	if (valid(latest, { loose: true }) && valid(have, { loose: true })) return gt(latest, have, { loose: true });
+	return latest !== have;
+}
+
+/** Pure diff against the local mirror (apt list --upgradable semantics):
+ * drift = mirrored latest is genuinely newer than what we have. The
+ * mirror is refreshed by catalogSync; updates are computed offline,
+ * exactly like APT. */
+export function checkUpdates(latestOf: (name: string) => string | undefined, installed: InstalledPkg[]): UpdateEntry[] {
+	const now = new Date().toISOString();
+	const updates: UpdateEntry[] = [];
+	for (const p of installed) {
+		const have = p.installed || p.pinned;
+		if (!have) continue;
+		const latest = latestOf(p.name);
+		if (latest && isNewer(latest, have)) {
+			updates.push({ name: p.name, installed: have, latest, detectedAt: now, ...(p.scope ? { scope: p.scope } : {}) });
+		}
+	}
+	return updates;
+}
+
+export interface WatcherOptions {
+	intervalMs: number;
+	onError?: (e: unknown) => void;
+}
+
+/** Producer loop: immediate check, then on a timer. Returns a stop function. */
+export function startWatcher(
+	latestOf: (name: string) => string | undefined,
+	stateDir: string,
+	readInstalled: () => InstalledPkg[],
+	opts: WatcherOptions,
+): () => void {
+	async function check(): Promise<void> {
+		try {
+			const updates = checkUpdates(latestOf, readInstalled());
+			await saveUpdates(stateDir, { checkedAt: new Date().toISOString(), updates });
+			log.info("updates check", { updates: updates.length });
+		} catch (e) {
+			opts.onError?.(e);
+		}
+	}
+	void check();
+	const timer = setInterval(() => void check(), opts.intervalMs);
+	return () => clearInterval(timer);
+}

package/service/src/index/build-index.ts

@@ -0,0 +1,256 @@
+/**
+ * build-index.ts — batch-generates a versioned snapshot across the whole
+ * local catalog (the createrepo/dpkg-scanpackages analog). Incremental:
+ * a package new to the catalog or whose npm date has advanced since it
+ * was last scored gets a real assessRegistryAdoption() call; a package
+ * whose catalog date hasn't moved is carried forward from the prior index
+ * untouched, at zero live-call cost. Local generation only -- publishing
+ * this file somewhere public is a separate, later decision.
+ *
+ * Deliberately never calls GitHub: assessRegistryAdoption()'s freshness
+ * dimension only takes the git-commit-based path when a caller passes it
+ * a candidateCommitAt, and this file never does. Computing that path (a
+ * GitHub Commits API call) for every cataloged package would blow through
+ * the unauthenticated 60 req/hour limit commit-freshness.ts's own
+ * single-attempt design was built around -- bulk generation instead
+ * always falls back to the npm publish-date proxy, by construction.
+ */
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { type AdoptionReport, assessRegistryAdoption, PI_COMMAND_NAME } from "../adoption/score.ts";
+import { catalogList, dbPath, openDb } from "../packages/db.ts";
+import type { Registry } from "../packages/package.ts";
+import { resolveCurrentPiVersion } from "../pi/pi-version.ts";
+import { writeJsonAtomic } from "../shared/atomic-json.ts";
+import { INDEX_FILE, PAGE_DELAY_MS } from "../shared/constants.ts";
+import { createLogger } from "../shared/log.ts";
+
+const log = createLogger("index");
+
+export interface PackageIndexEntry {
+	name: string;
+	version: string;
+	dimensions: AdoptionReport["dimensions"];
+	/** The catalog's own npm date this entry was scored against -- the
+	 * per-package staleness watermark the next run compares its current
+	 * catalog date to. Undefined when the catalog had no date for this
+	 * package at scoring time (rare; treated as "unknown, always rescore"
+	 * by the next run rather than assumed unchanged). A single global
+	 * generatedAt watermark would be wrong here: packages enter the catalog
+	 * and get scored at different times, so staleness must be per-package. */
+	date?: string;
+}
+
+export interface PackageIndex {
+	generatedAt: string;
+	packages: PackageIndexEntry[];
+	/** True when the local catalog held more entries than maxPackages --
+	 * confirmed live against this project's own real catalog (5,250
+	 * keywords:pi-package matches, overwhelmingly false positives from the
+	 * search itself, a separate known issue): an unbounded run hit npm's
+	 * downloads API 149 times with 429s in under three minutes and would
+	 * have run for hours. Never silently incomplete -- always stated. */
+	truncated: boolean;
+}
+
+/** Confirmed live this needs to stay small: even with downloads() removed,
+ * 500 packages against a real npm registry took long enough that two
+ * overlapping runs (the daemon's own maintenance-task tick and an
+ * on-demand CLI build) compounded into a shutdown the daemon's own
+ * SIGTERM grace period couldn't outlast, forcing a SIGABRT/coredump.
+ * Small and bounded beats generous here. */
+const DEFAULT_MAX_PACKAGES = 50;
+
+// Guards against the exact failure just described: the daemon's scheduled
+// maintenance tick and an on-demand `packed index build` both call into
+// this module inside the same process. Without this, both would run a
+// full generation concurrently against the same npm endpoints, doubling
+// load and compounding retry backoff. A concurrent caller gets the
+// in-flight run's own result instead of starting a second one.
+let inFlight: Promise<PackageIndex> | undefined;
+
+export interface IndexStatus {
+	stale: boolean;
+	generatedAt?: string;
+	packageCount?: number;
+	truncated?: boolean;
+}
+
+export interface BuildIndexOptions {
+	/** Politeness pause between per-package registry calls -- same role as
+	 * catalog.ts's PAGE_DELAY_MS. */
+	delayMs?: number;
+	currentPiVersion?: () => Promise<string | undefined>;
+	/** Explicit bound on how many cataloged packages one generation run will
+	 * process -- defaults to DEFAULT_MAX_PACKAGES. A run never silently
+	 * processes an unbounded catalog. */
+	maxPackages?: number;
+}
+
+/** Same per-directory-filename convention as db.ts's dbPath(). */
+export function indexPath(dir: string): string {
+	return join(dir, INDEX_FILE);
+}
+
+/**
+ * One assessRegistryAdoption() call per cataloged package -- npm registry
+ * data only, no GitHub. A single package failing its registry lookup
+ * (removed, renamed, transient error) is skipped and logged rather than
+ * failing the whole run.
+ *
+ * Deliberately never calls reg.downloads(): confirmed live against this
+ * project's own real catalog (5,250 entries, overwhelmingly false
+ * positives from the keywords:pi-package search itself, a separate known
+ * issue) that calling it per package hits npm's downloads API 429s within
+ * minutes -- two extra requests per package on top of info(). traction
+ * stays "unknown" for every bulk-generated entry, which is already the
+ * dimension's own honest fallback for missing download data, not a new
+ * failure mode.
+ */
+export function buildIndex(reg: Registry, catalogDir: string, options: BuildIndexOptions = {}): Promise<PackageIndex> {
+	if (inFlight) return inFlight;
+	const run = buildIndexNow(reg, catalogDir, options).finally(() => {
+		inFlight = undefined;
+	});
+	inFlight = run;
+	return run;
+}
+
+/**
+ * Partitions the current catalog against the prior index (when one exists)
+ * into three groups -- New (never scored before), Changed (scored before,
+ * but the catalog's date for it has advanced since), and Unchanged (scored
+ * before, same date). Identity (name presence) decides New vs. known;
+ * date decides Changed vs. Unchanged among known packages -- these are
+ * deliberately different questions (see this module's own research Doc):
+ * a package can be old on npm but new to *our* catalog, so date alone
+ * can never answer "have we scored this before."
+ */
+function partitionAgainstPriorIndex(
+	catalogPkgs: Array<{ name: string; date?: string }>,
+	priorByName: Map<string, PackageIndexEntry>,
+): { toScore: string[]; unchanged: PackageIndexEntry[] } {
+	const toScore: string[] = [];
+	const unchanged: PackageIndexEntry[] = [];
+	for (const pkg of catalogPkgs) {
+		const prior = priorByName.get(pkg.name);
+		if (!prior) {
+			toScore.push(pkg.name);
+			continue;
+		} // New
+		// Can't prove nothing changed without both dates -- rescore rather
+		// than assume, matching this codebase's "never guess" convention.
+		if (pkg.date === undefined || prior.date === undefined) {
+			toScore.push(pkg.name);
+			continue;
+		}
+		if (Date.parse(pkg.date) > Date.parse(prior.date)) {
+			toScore.push(pkg.name);
+			continue;
+		} // Changed
+		unchanged.push(prior); // Unchanged -- carried forward verbatim, zero live calls
+	}
+	return { toScore, unchanged };
+}
+
+async function buildIndexNow(reg: Registry, catalogDir: string, options: BuildIndexOptions): Promise<PackageIndex> {
+	const delayMs = options.delayMs ?? PAGE_DELAY_MS;
+	const currentPiVersion = options.currentPiVersion ?? resolveCurrentPiVersion;
+	const maxPackages = options.maxPackages ?? DEFAULT_MAX_PACKAGES;
+
+	const db = openDb(dbPath(catalogDir));
+	let catalogPkgs: Array<{ name: string; date?: string }>;
+	try {
+		catalogPkgs = catalogList(db).map((p) => ({ name: p.name, date: p.date }));
+	} finally {
+		db.close();
+	}
+
+	const priorIndex = readIndex(indexPath(catalogDir));
+	const priorByName = new Map((priorIndex?.packages ?? []).map((entry) => [entry.name, entry]));
+	const { toScore, unchanged } = partitionAgainstPriorIndex(catalogPkgs, priorByName);
+	const catalogDateByName = new Map(catalogPkgs.map((p) => [p.name, p.date]));
+
+	// The bound applies to the live-call queue specifically, not the whole
+	// catalog -- Unchanged carry-forwards are cheap local copies and were
+	// never the resource this cap exists to protect.
+	const truncated = toScore.length > maxPackages;
+	const names = toScore.slice(0, maxPackages);
+	if (truncated) log.warn("new/changed queue exceeds maxPackages, truncating this run", { queueSize: toScore.length, maxPackages });
+
+	// Skip both lookups entirely when nothing needs live scoring this run --
+	// an all-Unchanged catalog should make zero network calls, not one.
+	let piVersion: string | undefined;
+	let piModified: string | undefined;
+	if (names.length > 0) {
+		piVersion = await currentPiVersion();
+		if (reg.modifiedAt) {
+			try {
+				piModified = await reg.modifiedAt(PI_COMMAND_NAME);
+			} catch {
+				/* freshness stays explicitly unknown for every entry */
+			}
+		}
+	}
+
+	const scored: PackageIndexEntry[] = [];
+	for (const name of names) {
+		try {
+			const info = await reg.info(name);
+			if (reg.modifiedAt) {
+				try {
+					info.modified = await reg.modifiedAt(name);
+				} catch {
+					/* freshness proxy stays explicitly unknown */
+				}
+			}
+			// No candidateCommitAt argument here -- GitHub is never touched
+			// during bulk generation, by construction, not by omission.
+			const report = assessRegistryAdoption(info, piVersion, piModified);
+			scored.push({ name: info.name, version: info.version, dimensions: report.dimensions, date: catalogDateByName.get(name) });
+		} catch (e) {
+			log.warn("index entry failed, skipping", { name, error: e instanceof Error ? e.message : String(e) });
+		}
+		if (delayMs > 0) await Bun.sleep(delayMs);
+	}
+	return { generatedAt: new Date().toISOString(), packages: [...unchanged, ...scored], truncated };
+}
+
+/** Atomic write -- tmp file + rename, same partial-write-safety convention
+ * as security.ts's writeSecuritySettings. */
+export async function writeIndex(path: string, index: PackageIndex): Promise<void> {
+	await writeJsonAtomic(path, index, { trailingNewline: false });
+}
+
+export function readIndex(path: string): PackageIndex | undefined {
+	try {
+		const parsed = JSON.parse(readFileSync(path, "utf8")) as Partial<PackageIndex>;
+		if (typeof parsed.generatedAt === "string" && Array.isArray(parsed.packages)) return parsed as PackageIndex;
+		return undefined;
+	} catch {
+		return undefined;
+	}
+}
+
+export function indexStatus(path: string, ttlMs: number): IndexStatus {
+	const index = readIndex(path);
+	if (!index) return { stale: true };
+	return {
+		stale: Date.now() - Date.parse(index.generatedAt) > ttlMs,
+		generatedAt: index.generatedAt,
+		packageCount: index.packages.length,
+		truncated: index.truncated,
+	};
+}
+
+/** Build + write in one call -- the maintenance-task/CLI entry point. */
+export async function generateIndex(
+	reg: Registry,
+	catalogDir: string,
+	path: string,
+	options: BuildIndexOptions = {},
+): Promise<PackageIndex> {
+	const index = await buildIndex(reg, catalogDir, options);
+	await writeIndex(path, index);
+	return index;
+}

package/service/src/packages/catalog.ts

@@ -0,0 +1,61 @@
+/**
+ * catalog.ts — the sync pipeline (apt update / pkg update analog).
+ * Paginates the upstream registry into the local SQLite mirror and records
+ * sync metadata (the Release/repomd checksum role) in sync_meta.
+ */
+
+import { PI_PACKAGE_KEYWORD } from "../shared/constants.ts";
+import { createLogger } from "../shared/log.ts";
+import { dbPath, getSyncMeta, openDb, replaceAll } from "./db.ts";
+import type { Registry } from "./package.ts";
+
+const log = createLogger("catalog");
+
+import type { SyncMeta } from "./db.ts";
+
+export interface CatalogStatus {
+	stale: boolean;
+	meta?: SyncMeta;
+}
+
+export function catalogStatus(dir: string, ttlMs: number): CatalogStatus {
+	const db = openDb(dbPath(dir));
+	try {
+		const meta = getSyncMeta(db);
+		if (!meta) return { stale: true };
+		return { stale: Date.now() - Date.parse(meta.fetchedAt) > ttlMs, meta };
+	} finally {
+		db.close();
+	}
+}
+
+/** Full mirror sync: upstream pages → atomic SQLite replace. */
+export async function syncCatalog(reg: Registry, dir: string, query: string = PI_PACKAGE_KEYWORD): Promise<number> {
+	const t0 = Date.now();
+	log.info("mirror sync started", { query });
+	const packages = await reg.searchAll(query);
+	const db = openDb(dbPath(dir));
+	try {
+		replaceAll(db, packages, `npm:${query}`);
+		log.info("mirror sync complete", { packages: packages.length, ms: Date.now() - t0 });
+		return packages.length;
+	} finally {
+		db.close();
+	}
+}
+
+export function startCatalogSync(reg: Registry, dir: string, ttlMs: number, onError?: (e: unknown) => void): () => void {
+	async function sync(): Promise<void> {
+		try {
+			if (catalogStatus(dir, ttlMs).stale) {
+				const n = await syncCatalog(reg, dir);
+				log.info("scheduled sync complete", { packages: n });
+			}
+		} catch (e) {
+			onError?.(e);
+		}
+	}
+	void sync();
+	const timer = setInterval(() => void sync(), ttlMs);
+	return () => clearInterval(timer);
+}

package/service/src/packages/db.ts

@@ -0,0 +1,224 @@
+/**
+ * db.ts — the local registry index (SQLite), the pkgng/YUM model.
+ * Master-index role: sync_meta (source, time, count, payload checksum —
+ * the APT Release / repomd.xml analog). Payload: packages + FTS5 mirror.
+ */
+// Runtime-detected SQLite backend: bun:sqlite under Bun (CLI, daemon),
+// node:sqlite under Node ≥22.5 (pi's extension host — jiti runs on Node).
+// Both share the better-sqlite3 API shape; transactions are done manually
+// because node:sqlite has no .transaction() helper.
+
+import { mkdirSync } from "node:fs";
+import { createRequire } from "node:module";
+
+const require_ = createRequire(import.meta.url);
+const IS_BUN = typeof (globalThis as { Bun?: unknown }).Bun !== "undefined";
+const backend = IS_BUN
+	? (require_("bun:sqlite") as typeof import("bun:sqlite"))
+	: (require_("node:sqlite") as unknown as typeof import("bun:sqlite"));
+
+// Constructor + options differ: bun:sqlite exports Database({create}),
+// node:sqlite exports DatabaseSync (creates by default).
+const DatabaseCtor = ("DatabaseSync" in backend ? (backend as { DatabaseSync: unknown }).DatabaseSync : backend.Database) as new (
+	path: string,
+	opts?: { create?: boolean },
+) => Db;
+
+export interface DbStatement {
+	run(...params: unknown[]): { lastInsertRowid: number | bigint };
+	get(...params: unknown[]): unknown;
+	all(...params: unknown[]): unknown[];
+}
+
+export interface Db {
+	exec(sql: string): unknown;
+	prepare(sql: string): DbStatement;
+	close(): void;
+}
+
+function inTransaction<T>(db: Db, fn: () => T): T {
+	db.exec("BEGIN");
+	try {
+		const result = fn();
+		db.exec("COMMIT");
+		return result;
+	} catch (e) {
+		db.exec("ROLLBACK");
+		throw e;
+	}
+}
+
+import { createHash } from "node:crypto";
+import { join } from "node:path";
+import { DB_FILE } from "../shared/constants.ts";
+import type { Pkg } from "./package.ts";
+
+export interface SyncMeta {
+	source: string;
+	fetchedAt: string;
+	packageCount: number;
+	sha256: string;
+}
+
+export function dbPath(dir: string): string {
+	return join(dir, DB_FILE);
+}
+
+export function openDb(path: string): Db {
+	if (path !== ":memory:") mkdirSync(join(path, ".."), { recursive: true });
+	const db = IS_BUN ? new DatabaseCtor(path, { create: true }) : new DatabaseCtor(path);
+	db.exec("PRAGMA journal_mode = WAL");
+	db.exec(`CREATE TABLE IF NOT EXISTS packages (
+		name TEXT PRIMARY KEY,
+		version TEXT NOT NULL DEFAULT '',
+		description TEXT,
+		date TEXT
+	)`);
+	ensureColumn(db, "packages", "shape", "TEXT NOT NULL DEFAULT 'keyword-only'");
+	ensureColumn(db, "packages", "verified", "INTEGER NOT NULL DEFAULT 0");
+	ensureColumn(db, "packages", "evidence", "TEXT NOT NULL DEFAULT '[]'");
+	ensureColumn(db, "packages", "provenance_url", "TEXT");
+	ensureColumn(db, "packages", "trusted_publisher", "TEXT NOT NULL DEFAULT 'unknown'");
+	db.exec(`CREATE TABLE IF NOT EXISTS sync_meta (
+		id INTEGER PRIMARY KEY CHECK (id = 1),
+		source TEXT NOT NULL,
+		fetched_at TEXT NOT NULL,
+		package_count INTEGER NOT NULL,
+		sha256 TEXT NOT NULL
+	)`);
+	// FTS5 mirror; rebuilt wholesale on each sync.
+	db.exec(`CREATE VIRTUAL TABLE IF NOT EXISTS packages_fts USING fts5(name, description)`);
+	return db;
+}
+
+function ensureColumn(db: Db, table: string, column: string, declaration: string): void {
+	const columns = db.prepare(`PRAGMA table_info(${table})`).all() as Array<{ name: string }>;
+	if (!columns.some((item) => item.name === column)) db.exec(`ALTER TABLE ${table} ADD COLUMN ${column} ${declaration}`);
+}
+
+/** Canonical checksum over the payload — the Release-file analog: cheap
+ * change detection between syncs and integrity for the local mirror. */
+function payloadHash(pkgs: Pkg[]): string {
+	const h = createHash("sha256");
+	for (const p of pkgs)
+		h.update(
+			`${p.name}@${p.version}:${p.packageEvidence?.shape ?? "keyword-only"}:${p.packageEvidence?.verified === true ? 1 : 0}:${p.publication?.provenanceUrl ?? ""}\n`,
+		);
+	return h.digest("hex");
+}
+
+/** Atomic full-catalog replace (the mirror write side of `apt update`). */
+export function replaceAll(db: Db, pkgs: Pkg[], source: string): SyncMeta {
+	const meta: SyncMeta = {
+		source,
+		fetchedAt: new Date().toISOString(),
+		packageCount: pkgs.length,
+		sha256: payloadHash(pkgs),
+	};
+	// INSERT OR REPLACE: npm pagination is unstable — rankings shift between
+	// pages and a package can appear twice in one sync (rowid reuse is fine).
+	const insert = db.prepare(
+		"INSERT OR REPLACE INTO packages (name, version, description, date, shape, verified, evidence, provenance_url, trusted_publisher) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)",
+	);
+	const insertFts = db.prepare("INSERT INTO packages_fts (rowid, name, description) VALUES (?, ?, ?)");
+	inTransaction(db, () => {
+		db.exec("DELETE FROM packages");
+		db.exec("DELETE FROM packages_fts");
+		for (const p of pkgs) {
+			const { lastInsertRowid } = insert.run(
+				p.name,
+				p.version,
+				p.description ?? null,
+				p.date ?? null,
+				p.packageEvidence?.shape ?? "keyword-only",
+				p.packageEvidence?.verified === true ? 1 : 0,
+				JSON.stringify(p.packageEvidence?.evidence ?? []),
+				p.publication?.provenanceUrl ?? null,
+				p.publication?.trustedPublisher ?? "unknown",
+			);
+			insertFts.run(Number(lastInsertRowid), p.name, p.description ?? "");
+		}
+		db.prepare(
+			"INSERT INTO sync_meta (id, source, fetched_at, package_count, sha256) VALUES (1, ?, ?, ?, ?) " +
+				"ON CONFLICT(id) DO UPDATE SET source=excluded.source, fetched_at=excluded.fetched_at, " +
+				"package_count=excluded.package_count, sha256=excluded.sha256",
+		).run(meta.source, meta.fetchedAt, meta.packageCount, meta.sha256);
+	});
+	return meta;
+}
+
+export function getSyncMeta(db: Db): SyncMeta | undefined {
+	return db.prepare("SELECT source, fetched_at AS fetchedAt, package_count AS packageCount, sha256 FROM sync_meta WHERE id = 1").get() as
+		| SyncMeta
+		| undefined;
+}
+
+export function catalogList(db: Db, limit = 0, offset = 0): Pkg[] {
+	const sql =
+		"SELECT name, version, description, date, shape, verified, evidence, provenance_url AS provenanceUrl, trusted_publisher AS trustedPublisher FROM packages ORDER BY name" +
+		(limit > 0 ? ` LIMIT ${Math.floor(limit)} OFFSET ${Math.floor(offset)}` : "");
+	return mapPackageRows(db.prepare(sql).all());
+}
+
+/** FTS5 over the mirror (the `apt-cache search` analog). Sanitizes user
+ * input into AND-joined quoted terms; falls back to LIKE for hostile input. */
+export function searchLocal(db: Db, q: string, limit = 50): Pkg[] {
+	const terms = q.trim().split(/\s+/).filter(Boolean);
+	if (terms.length === 0) return [];
+	try {
+		const match = terms.map((t) => `"${t.replaceAll('"', '""')}"*`).join(" ");
+		return mapPackageRows(
+			db
+				.prepare(
+					`SELECT p.name, p.version, p.description, p.date, p.shape, p.verified, p.evidence,
+				        p.provenance_url AS provenanceUrl, p.trusted_publisher AS trustedPublisher
+				 FROM packages_fts f JOIN packages p ON p.rowid = f.rowid
+				 WHERE packages_fts MATCH ? ORDER BY p.verified DESC, rank LIMIT ?`,
+				)
+				.all(match, limit),
+		);
+	} catch {
+		// FTS syntax hostility → substring fallback
+		const like = `%${q}%`;
+		return mapPackageRows(
+			db
+				.prepare(
+					"SELECT name, version, description, date, shape, verified, evidence, provenance_url AS provenanceUrl, trusted_publisher AS trustedPublisher FROM packages WHERE name LIKE ? OR description LIKE ? ORDER BY verified DESC, name LIMIT ?",
+				)
+				.all(like, like, limit),
+		);
+	}
+}
+
+function mapPackageRows(rows: unknown[]): Pkg[] {
+	return (rows as Array<Record<string, unknown>>).map((row) => ({
+		name: String(row.name),
+		version: String(row.version ?? ""),
+		description: typeof row.description === "string" ? row.description : undefined,
+		date: typeof row.date === "string" ? row.date : undefined,
+		packageEvidence: {
+			shape: row.shape === "manifest" || row.shape === "conventional" ? row.shape : "keyword-only",
+			verified: row.verified === 1 || row.verified === true,
+			evidence: parseEvidence(row.evidence),
+		},
+		publication: {
+			provenanceUrl: typeof row.provenanceUrl === "string" ? row.provenanceUrl : undefined,
+			trustedPublisher: row.trustedPublisher === "verified" || row.trustedPublisher === "not-verified" ? row.trustedPublisher : "unknown",
+		},
+	}));
+}
+
+function parseEvidence(value: unknown): string[] {
+	try {
+		const parsed = JSON.parse(typeof value === "string" ? value : "[]") as unknown;
+		return Array.isArray(parsed) ? parsed.filter((item): item is string => typeof item === "string").slice(0, 20) : [];
+	} catch {
+		return [];
+	}
+}
+
+/** Latest mirrored version of one package (watcher's lookup). */
+export function latestVersion(db: Db, name: string): string | undefined {
+	const row = db.prepare("SELECT version FROM packages WHERE name = ?").get(name) as { version: string } | null;
+	return row?.version;
+}