@herbertgao/pi-extensions 2026.8.7 → 2026.8.8

package/node_modules/pi-lens/dist/tools/lens-diagnostics.js

@@ -349,9 +349,16 @@ captureLspStatusRepaint, getRuntime) {
 }
 // ── delta mode ────────────────────────────────────────────────────────────────
 function formatProjectDeltaDiagnostic(diagnostic, stale) {
-    const marker = diagnostic.semantic === "blocking" || diagnostic.severity === "error"
-        ? "🔴"
-        : "ℹ";
+    // #1944: a demoted row loses the authority marker along with its
+    // coordinate. It kept the 🔴 while its line was replaced by the stale
+    // marker, which is the same "changed the channel, not the body" defect the
+    // turn-end advisory carried — `formatFullMode` (this file, the `d.stale`
+    // arm of its marker) already drops the marker for exactly this reason.
+    const marker = stale
+        ? "○"
+        : diagnostic.semantic === "blocking" || diagnostic.severity === "error"
+            ? "🔴"
+            : "ℹ";
     const rule = diagnostic.rule ?? diagnostic.code ?? diagnostic.runner;
     const where = stale ? STALE_LINE_MARKER : `L${diagnostic.line ?? "?"}`;
     return `  ${marker} ${where}  ${rule}  ${diagnostic.message}`;

package/node_modules/pi-lens/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-lens",
-  "version": "4.1.0",
+  "version": "4.1.1",
   "type": "module",
   "description": "Real-time code feedback for pi — LSP, linters, formatters, type-checking, structural analysis & booboo",
   "repository": {
@@ -17,7 +17,7 @@
     "build": "tsc --project tsconfig.build.json",
     "build:dist": "node -e \"require('fs').rmSync('dist',{recursive:true,force:true})\" && npx --yes -p typescript@7.0.2 tsc --project tsconfig.dist.json --noCheck && npm run bundle:dist",
     "bundle:dist": "node scripts/bundle-dist.mjs",
-    "prepare": "npm run build:dist && node scripts/download-grammars.js --core --dest grammars",
+    "prepare": "npm run build:dist && node scripts/download-grammars.js --core --dest grammars && node scripts/setup-git-hooks.mjs && node scripts/warm-loader-cache.mjs",
     "lint": "tsc --project tsconfig.json",
     "watch": "tsc --watch",
     "test": "node scripts/with-test-lock.mjs -- vitest run",
@@ -80,6 +80,9 @@
     "scripts/grammars.lock.json",
     "scripts/analyze-pi-lens-logs.mjs",
     "scripts/install-selftest.mjs",
+    "scripts/lib/host-provided-deps.mjs",
+    "scripts/lib/warm-loader-cache.mjs",
+    "scripts/warm-loader-cache.mjs",
     "scripts/rpc-load-check.mjs",
     "README.md",
     "CHANGELOG.md",
@@ -89,30 +92,40 @@
   "dependencies": {
     "@ast-grep/cli": "^0.45.0",
     "@ast-grep/napi": "^0.45.0",
-    "@earendil-works/pi-tui": "^0.84.1",
     "js-yaml": "^5.2.2",
     "minimatch": "^10.2.6",
     "pidusage": "^4.0.1",
-    "typebox": "^1.0.0",
     "vscode-jsonrpc": "^9.0.0"
   },
   "peerDependencies": {
-    "@earendil-works/pi-coding-agent": "*"
+    "@earendil-works/pi-coding-agent": "*",
+    "@earendil-works/pi-tui": "^0.84.1",
+    "typebox": "^1.0.0"
   },
   "peerDependenciesMeta": {
     "@earendil-works/pi-coding-agent": {
       "optional": true
+    },
+    "@earendil-works/pi-tui": {
+      "optional": true
+    },
+    "typebox": {
+      "optional": true
     }
   },
   "optionalDependencies": {
+    "jiti": "^2.7.0",
     "web-tree-sitter": "0.25.10"
   },
   "devDependencies": {
     "@biomejs/biome": "^2.4.10",
     "@earendil-works/pi-coding-agent": "^0.84.1",
+    "@earendil-works/pi-tui": "^0.84.1",
     "@types/node": "^26.0.0",
     "@types/pidusage": "^2.0.5",
     "@vitest/coverage-v8": "^4.1.5",
+    "husky": "^9.1.7",
+    "typebox": "^1.0.0",
     "typescript": "^7.0.2",
     "typescript-language-server": "^5.1.3",
     "vitest": "^4.1.1"

package/node_modules/pi-lens/scripts/install-selftest.mjs

@@ -19,6 +19,20 @@
  * build-script-provided assets (ast-grep CLI binary + tree-sitter grammars)
  * that pnpm/bun skip by default. It runs no model and needs no credentials.
  *
+ * WHAT IT NO LONGER COVERS (#1926)
+ * pi supplies `typebox` and `@earendil-works/pi-tui` from its own runtime, so
+ * they are optional peers and no install vendors them. This probe is not pi, so
+ * those specifiers cannot resolve here, and `dist/index.js` throws on the FIRST
+ * one it imports. A host-provided miss is therefore recorded as EXPECTED rather
+ * than failed. The cost is real and stated plainly: evaluation stops there, so
+ * the entry probe no longer proves the whole bundled graph resolves, which is
+ * what #285 and #335 asked it to prove. Any OTHER unresolved specifier still
+ * fails hard, and the per-module probes below (file-utils, complexity-client,
+ * bootstrap) still cover that graph directly. The surviving POSITIVE proof that
+ * the entry loads in full is the install-smoke `pi-load` job: it installs pi,
+ * installs pi-lens through pi, and confirms over RPC that pi-lens registered
+ * its commands.
+ *
  * USAGE
  *   bun  scripts/install-selftest.mjs     # faithful: pi's runtime is bun
  *   node scripts/install-selftest.mjs     # also works
@@ -28,10 +42,11 @@
  */
 
 import { execFileSync } from "node:child_process";
+import * as fs from "node:fs";
 import { createRequire } from "node:module";
-import { fileURLToPath } from "node:url";
 import * as path from "node:path";
-import * as fs from "node:fs";
+import { fileURLToPath } from "node:url";
+import { HOST_PROVIDED_PACKAGES } from "./lib/host-provided-deps.mjs";
 
 const here = path.dirname(fileURLToPath(import.meta.url));
 const pkgRoot = path.resolve(here, "..");
@@ -42,6 +57,26 @@ const results = [];
 const record = (name, kind, ok, detail = "") =>
 	results.push({ name, kind, ok, detail });
 
+/**
+ * Which host-provided package, if any, a resolution error is about. Returns
+ * undefined for every other error, so an unrelated missing package still fails.
+ */
+function hostProvidedMiss(err) {
+	const text = `${err?.code || ""} ${err?.message || err}`;
+	if (
+		!/ERR_MODULE_NOT_FOUND|Cannot find (package|module)|ResolveMessage/.test(
+			text,
+		)
+	) {
+		return undefined;
+	}
+	return HOST_PROVIDED_PACKAGES.find((name) =>
+		new RegExp(
+			`['"\`]${name.replace(/[/\\^$*+?.()|[\]{}]/g, "\\$&")}['"\`]`,
+		).test(text),
+	);
+}
+
 /** Import a module by URL and record whether its (eager) dep graph resolved. */
 async function probeImport(name, relPath) {
 	const url = new URL(
@@ -51,7 +86,24 @@ async function probeImport(name, relPath) {
 		await import(url.href);
 		record(name, "resolve", true);
 	} catch (err) {
-		record(name, "resolve", false, `${err?.code || ""} ${err?.message || err}`.trim());
+		// #1926: pi supplies these; outside pi they cannot resolve, and the entry
+		// throws on the first one. Expected, not a regression. Anything else is.
+		const host = hostProvidedMiss(err);
+		if (host) {
+			record(
+				name,
+				"expected",
+				true,
+				`stopped at host-provided '${host}' — pi supplies it; graph beyond this point unproven here (#1926)`,
+			);
+			return;
+		}
+		record(
+			name,
+			"resolve",
+			false,
+			`${err?.code || ""} ${err?.message || err}`.trim(),
+		);
 	}
 }
 
@@ -61,27 +113,53 @@ function probeResolve(spec) {
 		require.resolve(spec);
 		record(spec, "resolve", true);
 	} catch (err) {
-		record(spec, "resolve", false, `${err?.code || ""} ${err?.message || err}`.trim());
+		record(
+			spec,
+			"resolve",
+			false,
+			`${err?.code || ""} ${err?.message || err}`.trim(),
+		);
 	}
 }
 
 // --- 1. The documented failure-point modules (eager bare imports) ----------
 await probeImport("dist/index.js (entry)", "dist/index.js");
-await probeImport("clients/file-utils.js (→ minimatch)", "dist/clients/file-utils.js");
-await probeImport("clients/complexity-client.js (→ tree-sitter)", "dist/clients/complexity-client.js");
-await probeImport("clients/bootstrap.js (→ all analyzers)", "dist/clients/bootstrap.js");
+await probeImport(
+	"clients/file-utils.js (→ minimatch)",
+	"dist/clients/file-utils.js",
+);
+await probeImport(
+	"clients/complexity-client.js (→ tree-sitter)",
+	"dist/clients/complexity-client.js",
+);
+await probeImport(
+	"clients/bootstrap.js (→ all analyzers)",
+	"dist/clients/bootstrap.js",
+);
 
 // --- 2. Direct bare-specifier resolution -----------------------------------
-for (const spec of [
+// Host-provided packages are subtracted, not listed as exceptions: pi resolves
+// them from its own runtime, so nothing installs them and probing one here is
+// guaranteed to fail (#1926). The subtraction reads the same list the bundler
+// and the packaging tests use, so it cannot drift.
+const BARE_SPECIFIERS = [
 	"minimatch",
 	"typebox",
 	"js-yaml",
 	"vscode-jsonrpc",
 	"web-tree-sitter",
 	"@ast-grep/napi",
-]) {
+].filter((spec) => !HOST_PROVIDED_PACKAGES.includes(spec));
+
+for (const spec of BARE_SPECIFIERS) {
 	probeResolve(spec);
 }
+record(
+	"host-provided specifiers skipped",
+	"expected",
+	true,
+	`${HOST_PROVIDED_PACKAGES.join(", ")} — pi supplies these (#1926)`,
+);
 
 // --- 3. Spawned-binary tools (the universal net) ----------------------------
 // For every tool that ships its binary in a per-platform npm package
@@ -121,11 +199,21 @@ try {
 			});
 			record(label, "tool", true, bin);
 		} catch (err) {
-			record(label, "tool", false, `${bin} failed to run: ${err?.message || err}`);
+			record(
+				label,
+				"tool",
+				false,
+				`${bin} failed to run: ${err?.message || err}`,
+			);
 		}
 	}
 } catch (err) {
-	record("spawned-tool probe", "tool", false, `installer load failed: ${err?.message || err}`);
+	record(
+		"spawned-tool probe",
+		"tool",
+		false,
+		`installer load failed: ${err?.message || err}`,
+	);
 }
 
 // tree-sitter grammars — download-grammars.js postinstall writes them into

package/node_modules/pi-lens/scripts/lib/host-provided-deps.mjs

@@ -0,0 +1,75 @@
+/**
+ * Single source of truth for the packages `scripts/bundle-dist.mjs` keeps out of
+ * the dist bundle, split by the REASON they stay external. #1926.
+ *
+ * HOST_PROVIDED_PACKAGES
+ *   pi ships these inside its own runtime (`@earendil-works/pi-coding-agent`'s
+ *   node_modules). They must be declared as OPTIONAL peer dependencies plus dev
+ *   dependencies, never as runtime `dependencies`, because a runtime dependency
+ *   makes `npm install --omit=dev` — the command pi runs for a `git:` install —
+ *   vendor a private second copy into the extension's own node_modules. Node
+ *   then resolves the bare specifier to that copy and evaluates a whole extra
+ *   module graph at import. That is #1926: vendoring `typebox` and
+ *   `@earendil-works/pi-tui` cost 720ms of the 838ms git-install import, and
+ *   removing the copies took the PI_TIMING module import from 941ms to ~180ms.
+ *
+ *   The three entries are NOT interchangeable at runtime. pi resolves the bare
+ *   specifiers `typebox` and `@earendil-works/pi-tui` for an extension, so
+ *   VALUE imports of those work with no copy on disk — verified by hiding both
+ *   from the dogfood install and re-running under PI_TIMING (#1926), and by
+ *   `@tintinweb/pi-subagents`, which declares pi-tui as a peer and ships no
+ *   copy. `@earendil-works/pi-coding-agent` is different: it is not resolvable
+ *   from an extension at all, so pi-lens imports it TYPE-ONLY and inlines the
+ *   runtime helpers it needs. `tests/host-sdk-type-only.test.ts` enforces that
+ *   separate rule (#1334 S6); do not read this list as permission to
+ *   value-import the host SDK.
+ *
+ * LAZY_NATIVE_PACKAGES
+ *   Native addon / wasm, dynamic-imported by absolute file:// URL at call time.
+ *   They stay external because esbuild cannot inline a .node or .wasm, and they
+ *   cost nothing at load because nothing imports them statically.
+ *
+ * `tests/packaging.test.ts` pins both invariants against package.json and
+ * against the built dist entry, so this list cannot drift from what ships.
+ */
+
+/**
+ * Host-provided packages the extension VALUE-imports. pi resolves these bare
+ * specifiers at runtime, so the compiled entry cannot load without them.
+ * Outside pi — a bare `node dist/index.js` in a CI smoke check — nothing
+ * supplies them, so a job that wants a FULL load has to install them first, the
+ * way pi does. `scripts/supply-host-provided-deps.mjs` does that.
+ */
+export const HOST_PROVIDED_RUNTIME_PACKAGES = Object.freeze([
+	"typebox",
+	"@earendil-works/pi-tui",
+]);
+
+/**
+ * Host-provided packages the extension imports TYPE-ONLY. pi does not resolve
+ * these for an extension at all, which is why every runtime helper pi-lens
+ * needs from the host SDK is inlined instead; `tests/host-sdk-type-only.test.ts`
+ * enforces that (#1334 S6). Never install one of these to make a load succeed:
+ * the transitive tree has nested paths that exceed Windows MAX_PATH.
+ */
+export const HOST_PROVIDED_TYPE_ONLY_PACKAGES = Object.freeze([
+	"@earendil-works/pi-coding-agent",
+]);
+
+/** Everything pi supplies, so pi-lens must never declare it a dependency. */
+export const HOST_PROVIDED_PACKAGES = Object.freeze([
+	...HOST_PROVIDED_RUNTIME_PACKAGES,
+	...HOST_PROVIDED_TYPE_ONLY_PACKAGES,
+]);
+
+/** Native/wasm packages dynamic-imported by absolute path at call time. */
+export const LAZY_NATIVE_PACKAGES = Object.freeze([
+	"@ast-grep/napi",
+	"web-tree-sitter",
+]);
+
+/** Everything esbuild must NOT inline into dist/index.js. */
+export const BUNDLE_EXTERNALS = Object.freeze([
+	...HOST_PROVIDED_PACKAGES,
+	...LAZY_NATIVE_PACKAGES,
+]);

package/node_modules/pi-lens/scripts/lib/warm-loader-cache.mjs

@@ -0,0 +1,285 @@
+/**
+ * Pure helpers for `scripts/warm-loader-cache.mjs` (#1926).
+ *
+ * pi loads an extension through jiti (`createJiti(..., { moduleCache: false,
+ * alias: … })` in `@earendil-works/pi-coding-agent`'s
+ * `dist/core/extensions/loader.js`). jiti transforms the entry with Babel and
+ * stores the result in a filesystem cache. pi-lens's `dist/index.js` is a ~4MB
+ * esbuild bundle, so that transform costs seconds: the first session after a
+ * `git:` install or update measured 4847ms of `module import`, against a 138ms
+ * steady state once the cache is warm (#1926 field report).
+ *
+ * The fix is to pay that transform at install time instead of in the first
+ * interactive session. `prepare` already builds `dist/`, so the last step of
+ * the chain runs the same transform through the same jiti, writing the same
+ * cache file pi will later read.
+ *
+ * WHY THE WARM PRODUCES A HIT FOR THE REAL LOADER
+ *
+ * jiti keys a cache entry on the transformed file, not on the jiti instance
+ * (see `getCache` in `jiti/dist/jiti.cjs`):
+ *
+ *   <basename(dirname(file))>-<basename(file) up to the first dot>
+ *   + "+map" if sourceMaps + ".i" if interopDefault
+ *   + "." + md5(file).slice(0, 8)
+ *   + ".mjs" for an async import, ".cjs" otherwise
+ *
+ * and it validates the stored body against a trailing
+ * ` /* v<TRANSFORM_VERSION>-<md5(source).slice(0,16)> *\/` marker. So the warm
+ * has to agree with pi on three things only: the absolute path of the entry,
+ * the cache directory, and the transform itself. Everything else — the alias
+ * map, `moduleCache`, which package the jiti instance was created from — is
+ * outside the key AND outside the transform. Measured, not assumed: running
+ * this warm over the dogfood install's `dist/index.js` produced a cache file
+ * byte-identical to the one pi had written, both with pi's alias map and with
+ * no alias map at all.
+ *
+ * The marker is also the safety net. If pi ships a jiti whose transform version
+ * or Babel output differs, pi recomputes the marker, does not match, and simply
+ * re-transforms. A mismatched warm costs the install a few seconds and buys
+ * nothing; it can never hand pi the wrong code.
+ */
+
+import { createHash, getFips } from "node:crypto";
+
+/**
+ * Mirror of jiti's `utils_hash`: md5 truncated to `length` hex characters, or
+ * sha256 where FIPS mode forbids md5. jiti makes the same substitution, so the
+ * two agree on every machine.
+ *
+ * @param {string} text
+ * @param {number} [length]
+ * @returns {string}
+ */
+export function jitiHash(text, length = 8) {
+	let fips = false;
+	try {
+		fips = Boolean(getFips?.());
+	} catch {
+		fips = false;
+	}
+	return createHash(fips ? "sha256" : "md5")
+		.update(text)
+		.digest("hex")
+		.slice(0, length);
+}
+
+/**
+ * The cache file jiti writes for an async import of `entry`.
+ *
+ * Mirror of jiti's `getCache` naming:
+ * `<basename(dirname(file))>-<basename up to the first dot>.<hash(file)>.mjs`.
+ * jiti hashes the POSIX-normalised absolute path, so the separators are
+ * converted here. The drive-letter case is left exactly as the caller resolved
+ * it, because jiti does not touch it either. Verified against pi's own cache
+ * directory: the md5 of the dogfood install's forward-slashed entry path,
+ * truncated to 8 characters, is the `db18768f` in the
+ * `dist-index.db18768f.mjs` pi had already written.
+ *
+ * @param {string} entry absolute path to the extension entry
+ * @returns {string}
+ */
+export function expectedCacheFileName(entry) {
+	const posix = entry.split("\\").join("/");
+	const segments = posix.split("/");
+	const base = segments.pop() ?? posix;
+	const parent = segments.pop() ?? "";
+	const dot = base.indexOf(".");
+	const stem = dot <= 0 ? base : base.slice(0, dot);
+	return `${parent}-${stem}.${jitiHash(posix)}.mjs`;
+}
+
+/**
+ * Did the warm actually leave a cache entry pi can use?
+ *
+ * Elapsed time is not evidence. jiti can return from an import having written
+ * nothing, and every such path exits 0:
+ *
+ *   - the cache directory is not writable. jiti's `prepareCacheDir` catches
+ *     that, sets `fsCache` to false, and transforms in memory from then on.
+ *   - the entry imported natively and nothing needed transforming. For an
+ *     async-imported ESM `.js` file jiti's `evalModule` attempts a native
+ *     import UNCONDITIONALLY, and only falls back to the transform when that
+ *     import rejects. So the cache exists at all because native import fails in
+ *     a real `--omit=dev` install, where the host-provided specifiers do not
+ *     resolve. That is the same reason pi's own load transforms the bundle,
+ *     which is why the warm and pi agree — but it is a property of the
+ *     environment, not of this script.
+ *   - a cache entry exists but does not match the source. jiti validates the
+ *     body against a trailing version-and-source-hash marker, so a stale or
+ *     truncated file is a miss for pi and the session pays the transform.
+ *
+ * Checking the file is what turns "the import returned" into "the warm's own
+ * jiti cached this entry, with these versions". It is not a promise about pi:
+ * pi-side drift shows up as a version delta between this record and pi's, which
+ * is a thing to read from the log, not something an install can detect.
+ * An absent entry always warrants a look, never a shrug.
+ *
+ * @param {object} args
+ * @param {string} args.cacheDir
+ * @param {string} args.fileName
+ * @param {string} args.source contents of the entry, for the marker check
+ * @param {object} args.fsDeps
+ * @param {(p: string) => boolean} args.fsDeps.existsSync
+ * @param {(p: string) => string} args.fsDeps.readFileSync
+ * @param {(p: string) => boolean} args.fsDeps.isWritable
+ * @returns {{ok: boolean, reason: string | null, transformVersion: string | null}}
+ */
+export function verifyCacheEntry({ cacheDir, fileName, source, fsDeps }) {
+	const file = `${cacheDir}/${fileName}`;
+	if (!fsDeps.existsSync(file)) {
+		if (!fsDeps.isWritable(cacheDir)) {
+			return {
+				ok: false,
+				reason: `cache directory is not writable: ${cacheDir}`,
+				transformVersion: null,
+			};
+		}
+		// Deliberately generic. Several routes end here — a native import that
+		// needed no transform, a transform that threw before the write — and this
+		// check cannot tell them apart, so it does not name one.
+		return {
+			ok: false,
+			reason: `no cache entry was written: ${fileName}`,
+			transformVersion: null,
+		};
+	}
+	let body;
+	try {
+		body = fsDeps.readFileSync(file);
+	} catch (err) {
+		const message = err instanceof Error ? err.message : String(err);
+		return {
+			ok: false,
+			reason: `cache entry unreadable: ${message}`,
+			transformVersion: null,
+		};
+	}
+	const marker = /\/\* v([^-\s]+)-([0-9a-f]+) \*\/\s*$/.exec(body);
+	if (!marker) {
+		return {
+			ok: false,
+			reason: "cache entry has no jiti version marker — pi will re-transform",
+			transformVersion: null,
+		};
+	}
+	if (marker[2] !== jitiHash(source, marker[2].length)) {
+		return {
+			ok: false,
+			reason:
+				"cache entry does not match the built entry — pi will re-transform",
+			transformVersion: marker[1],
+		};
+	}
+	return { ok: true, reason: null, transformVersion: marker[1] };
+}
+
+/**
+ * Mirror of jiti's `prepareCacheDir` fallback branch.
+ *
+ * jiti picks `<dir of the file that created the jiti instance>/node_modules/
+ * .cache/jiti` when that `node_modules` exists, and `<tmpdir>/jiti` otherwise.
+ * pi creates its instance from `dist/core/extensions/loader.js` inside the
+ * installed `@earendil-works/pi-coding-agent`, which has no `node_modules`
+ * sibling, so pi always lands on the tmpdir branch. The warm therefore passes
+ * `<tmpdir>/jiti` EXPLICITLY rather than letting jiti derive a directory from
+ * this repo's layout: `scripts/` has no `node_modules` sibling today, but a
+ * script moved one level up would silently start filling a private cache that
+ * pi never reads.
+ *
+ * The TMPDIR dance below is jiti's, kept verbatim so the two agree on machines
+ * where TMPDIR is set to the current directory.
+ *
+ * @param {object} deps
+ * @param {() => string} deps.tmpdir
+ * @param {Record<string, string | undefined>} deps.env
+ * @param {() => string} deps.cwd
+ * @param {(a: string, b: string) => string} deps.join
+ * @returns {string}
+ */
+export function resolveJitiCacheDir({ tmpdir, env, cwd, join }) {
+	let dir = tmpdir();
+	if (env.TMPDIR && dir === cwd() && !env.JITI_RESPECT_TMPDIR_ENV) {
+		const saved = env.TMPDIR;
+		delete env.TMPDIR;
+		dir = tmpdir();
+		env.TMPDIR = saved;
+	}
+	return join(dir, "jiti");
+}
+
+/**
+ * Alias every host-provided specifier to a path that cannot exist.
+ *
+ * The warm only needs the TRANSFORM of `dist/index.js`; jiti writes the cache
+ * entry before it evaluates the module. Evaluation then walks the bundle's
+ * external imports, none of which resolve outside pi. Pointing the
+ * host-provided ones at a stub makes that walk stop at the first one instead of
+ * resolving unrelated packages first, so the warm does the least work it can
+ * and always ends the same way. Derived from the shared host-provided list so
+ * it cannot drift from what `bundle-dist.mjs` keeps external.
+ *
+ * @param {readonly string[]} hostProvidedPackages
+ * @returns {Record<string, string>}
+ */
+export function buildStubAliases(hostProvidedPackages) {
+	/** @type {Record<string, string>} */
+	const alias = {};
+	for (const name of hostProvidedPackages) {
+		alias[name] = STUB_TARGET;
+	}
+	return alias;
+}
+
+/** A path no filesystem resolves, so aliased imports fail immediately. */
+export const STUB_TARGET = "/__pi-lens-warm-cache-stub__";
+
+/**
+ * Decide whether the warm can run, and say why not when it cannot.
+ *
+ * Every reason is a skip, never a failure: `prepare` also builds `dist/` and
+ * downloads grammars, and those steps MUST fail loudly. Cache warming is an
+ * optimisation, so it runs last and reports rather than throws — the same
+ * posture as `scripts/setup-git-hooks.mjs` (#1804).
+ *
+ * @param {object} state
+ * @param {Record<string, string | undefined>} state.env
+ * @param {boolean} state.distEntryExists
+ * @param {boolean} state.jitiResolvable
+ * @returns {string | null} skip reason, or null to proceed
+ */
+export function warmSkipReason({ env, distEntryExists, jitiResolvable }) {
+	const optOut = env.PI_LENS_SKIP_WARM_CACHE;
+	if (typeof optOut === "string" && optOut.length > 0) {
+		return "PI_LENS_SKIP_WARM_CACHE is set";
+	}
+	if (!distEntryExists) {
+		return "dist/index.js is missing — nothing to warm";
+	}
+	if (!jitiResolvable) {
+		// jiti is an optionalDependency, so `--omit=optional` (or a failed
+		// optional install) legitimately leaves it absent.
+		return "jiti is not installed — install ran without optional dependencies";
+	}
+	return null;
+}
+
+/**
+ * Keep the install log bounded: one line per install, newest last.
+ *
+ * @param {string[]} existingLines
+ * @param {string} line
+ * @param {number} [max]
+ * @returns {string[]}
+ */
+export function appendBounded(
+	existingLines,
+	line,
+	max = INSTALL_LOG_MAX_LINES,
+) {
+	const lines = [...existingLines.filter((l) => l.trim().length > 0), line];
+	return lines.slice(Math.max(0, lines.length - max));
+}
+
+/** Cap for `~/.pi-lens/install.log`. */
+export const INSTALL_LOG_MAX_LINES = 100;