pi-must-have-extension 0.4.13 → 0.4.15

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## [0.4.15] - 2026-06-01
+
+### Changed
+- Deferred config-loader and debug-logger module loading to reduce extension startup work.
+- Widened the Pi coding-agent peer dependency range to include `^0.77.0 || ^0.78.0` and aligned the development dependency to `^0.78.0`.
+
+## [0.4.14] - 2026-05-26
+
+### Changed
+- Widened peer dependency ranges to `^0.74.0 || ^0.75.0`.
+- Aligned dev dependencies to `^0.75.5`.
+
 ## [0.4.13] - 2026-05-22
 
 ### Changed

package/package.json

@@ -1,72 +1,72 @@
-{
-  "name": "pi-must-have-extension",
-  "version": "0.4.13",
-  "description": "RFC 2119 keyword normalizer extension for the Pi coding agent.",
-  "type": "module",
-  "main": "./index.ts",
-  "exports": {
-    ".": "./index.ts"
-  },
-  "files": [
-    "index.ts",
-    "src",
-    "asset",
-    "config/config.example.jsonc",
-    "config/replacements.custom-sample.jsonc",
-    "README.md",
-    "CHANGELOG.md",
-    "LICENSE",
-    "tsconfig.json"
-  ],
-  "scripts": {
-    "build": "tsc -p tsconfig.json --noEmit",
-    "lint": "npm run build",
-    "test": "node --experimental-strip-types --test test/**/*.test.ts",
-    "check": "npm run lint && npm run test"
-  },
-  "keywords": [
-    "pi-package",
-    "pi-extension",
-    "pi-coding-agent",
-    "pi",
-    "coding-agent",
-    "rfc2119",
-    "rfc8174",
-    "bcp14",
-    "prompt-normalization",
-    "prompt-rewrite",
-    "prompt-engineering",
-    "keyword-normalization",
-    "compliance",
-    "jsonc"
-  ],
-  "author": "MasuRii",
-  "license": "MIT",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/MasuRii/pi-must-have-extension.git"
-  },
-  "homepage": "https://github.com/MasuRii/pi-must-have-extension#readme",
-  "bugs": {
-    "url": "https://github.com/MasuRii/pi-must-have-extension/issues"
-  },
-  "engines": {
-    "node": ">=20"
-  },
-  "publishConfig": {
-    "access": "public"
-  },
-  "pi": {
-    "extensions": [
-      "./index.ts"
-    ]
-  },
-  "peerDependencies": {
-    "@earendil-works/pi-coding-agent": "^0.75.4"
-  },
-  "devDependencies": {
-    "@types/node": "^25.9.1",
-    "typescript": "^6.0.3",
-    "@earendil-works/pi-coding-agent": "^0.75.4"
-  }
-}
+{
+  "name": "pi-must-have-extension",
+  "version": "0.4.15",
+  "description": "RFC 2119 keyword normalizer extension for the Pi coding agent.",
+  "type": "module",
+  "main": "./index.ts",
+  "exports": {
+    ".": "./index.ts"
+  },
+  "files": [
+    "index.ts",
+    "src",
+    "asset",
+    "config/config.example.jsonc",
+    "config/replacements.custom-sample.jsonc",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE",
+    "tsconfig.json"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json --noEmit",
+    "lint": "npm run build",
+    "test": "node --experimental-strip-types --test test/**/*.test.ts",
+    "check": "npm run lint && npm run test"
+  },
+  "keywords": [
+    "pi-package",
+    "pi-extension",
+    "pi-coding-agent",
+    "pi",
+    "coding-agent",
+    "rfc2119",
+    "rfc8174",
+    "bcp14",
+    "prompt-normalization",
+    "prompt-rewrite",
+    "prompt-engineering",
+    "keyword-normalization",
+    "compliance",
+    "jsonc"
+  ],
+  "author": "MasuRii",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/MasuRii/pi-must-have-extension.git"
+  },
+  "homepage": "https://github.com/MasuRii/pi-must-have-extension#readme",
+  "bugs": {
+    "url": "https://github.com/MasuRii/pi-must-have-extension/issues"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "pi": {
+    "extensions": [
+      "./index.ts"
+    ]
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "^0.74.0 || ^0.75.0"
+  },
+  "devDependencies": {
+    "@types/node": "^25.9.1",
+    "typescript": "^6.0.3",
+    "@earendil-works/pi-coding-agent": "^0.75.5"
+  }
+}

package/src/constants.ts

@@ -1,8 +1,33 @@
-import { getAgentDir } from "@earendil-works/pi-coding-agent";
 import { homedir } from "node:os";
 import { join } from "node:path";
+import { fileURLToPath } from "node:url";
 import type { MustHaveExtensionConfig } from "./types.js";
 
+function normalizeAgentDirPath(path: string): string {
+	if (path === "~") {
+		return homedir();
+	}
+
+	if (path.startsWith("~/") || (process.platform === "win32" && path.startsWith("~\\"))) {
+		return join(homedir(), path.slice(2));
+	}
+
+	if (/^file:\/\//.test(path)) {
+		return fileURLToPath(path);
+	}
+
+	return path;
+}
+
+function getAgentDir(): string {
+	const envDir = process.env.PI_CODING_AGENT_DIR;
+	if (envDir) {
+		return normalizeAgentDirPath(envDir);
+	}
+
+	return join(homedir(), ".pi", "agent");
+}
+
 export const EXTENSION_NAME = "pi-must-have-extension";
 export const AGENT_DIR = getAgentDir();
 export const CONFIG_DIR = join(AGENT_DIR, "extensions", EXTENSION_NAME);

package/src/index.ts

@@ -6,15 +6,62 @@ import {
 	LEGACY_OPENCODE_CONFIG_PATH,
 	LEGACY_PI_MUST_HAVE_PLUGIN_CONFIG_PATH,
 } from "./constants.js";
-import { ensureConfigExists, loadConfig } from "./config/config-loader.js";
-import { writeDebugLog } from "./debug-logger.js";
 import { applyReplacements, shouldSkipInput } from "./replacements/replacement-engine.js";
 
+type ConfigLoaderModule = typeof import("./config/config-loader.js");
+type DebugLoggerModule = typeof import("./debug-logger.js");
+
 interface ReplacementDebugDetail {
 	value: string;
 	count: number;
 }
 
+let configLoaderModule: ConfigLoaderModule | undefined;
+let configLoaderModulePromise: Promise<ConfigLoaderModule> | undefined;
+let debugLoggerModule: DebugLoggerModule | undefined;
+let debugLoggerModulePromise: Promise<DebugLoggerModule> | undefined;
+
+function loadConfigLoaderModule(): Promise<ConfigLoaderModule> {
+	if (configLoaderModule) {
+		return Promise.resolve(configLoaderModule);
+	}
+
+	configLoaderModulePromise ??= import("./config/config-loader.js").then((module) => {
+		configLoaderModule = module;
+		return module;
+	});
+	return configLoaderModulePromise;
+}
+
+function loadDebugLoggerModule(): Promise<DebugLoggerModule> {
+	if (debugLoggerModule) {
+		return Promise.resolve(debugLoggerModule);
+	}
+
+	debugLoggerModulePromise ??= import("./debug-logger.js").then((module) => {
+		debugLoggerModule = module;
+		return module;
+	});
+	return debugLoggerModulePromise;
+}
+
+async function writeDebugLogWhenEnabled(
+	enabled: boolean,
+	event: string,
+	payload: Record<string, unknown> = {},
+): Promise<void> {
+	if (!enabled) {
+		return;
+	}
+
+	try {
+		const { writeDebugLog } = await loadDebugLoggerModule();
+		writeDebugLog(true, event, payload);
+	} catch {
+		// Debug logging must never affect extension behavior.
+	}
+}
+
 function buildReplacementDebugDetails(
 	counts: Map<string, number>,
 	replacements: Record<string, string>,
@@ -34,30 +81,31 @@ function buildReplacementDebugDetails(
 export default function mustHaveExtension(pi: ExtensionAPI): void {
 	const warnedMessages = new Set<string>();
 
-	const warnOnce = (
+	const warnOnce = async (
 		message: string,
 		ctx: Pick<ExtensionContext, "hasUI" | "ui">,
 		debugEnabled: boolean,
-	): void => {
+	): Promise<void> => {
 		if (warnedMessages.has(message)) {
 			return;
 		}
 		warnedMessages.add(message);
-		writeDebugLog(debugEnabled, "warning", { message });
+		await writeDebugLogWhenEnabled(debugEnabled, "warning", { message });
 		if (ctx.hasUI) {
 			ctx.ui.notify(message, "warning");
 		}
 	};
 
 	pi.on("session_start", async (_event, ctx) => {
+		const { ensureConfigExists, loadConfig } = await loadConfigLoaderModule();
 		const ensureResult = ensureConfigExists();
 		const loaded = loadConfig();
 		const debugEnabled = loaded.config.debug;
 		if (ensureResult.error) {
-			warnOnce(ensureResult.error, ctx, debugEnabled);
+			await warnOnce(ensureResult.error, ctx, debugEnabled);
 		}
 		if (ensureResult.migratedFrom) {
-			warnOnce(
+			await warnOnce(
 				`${EXTENSION_NAME}: migrated legacy config from ${ensureResult.migratedFrom} to ${CONFIG_PATH}.`,
 				ctx,
 				debugEnabled,
@@ -65,11 +113,11 @@ export default function mustHaveExtension(pi: ExtensionAPI): void {
 		}
 
 		if (loaded.warning) {
-			warnOnce(loaded.warning, ctx, debugEnabled);
+			await warnOnce(loaded.warning, ctx, debugEnabled);
 		}
 
 		if (loaded.source === "legacy_pi_plugin") {
-			warnOnce(
+			await warnOnce(
 				`${EXTENSION_NAME}: using legacy config ${LEGACY_PI_MUST_HAVE_PLUGIN_CONFIG_PATH}. Move it to ${CONFIG_PATH}.`,
 				ctx,
 				debugEnabled,
@@ -77,7 +125,7 @@ export default function mustHaveExtension(pi: ExtensionAPI): void {
 		}
 
 		if (loaded.source === "legacy_plugin") {
-			warnOnce(
+			await warnOnce(
 				`${EXTENSION_NAME}: using legacy config ${LEGACY_MUST_HAVE_PLUGIN_CONFIG_PATH}. Move it to ${CONFIG_PATH}.`,
 				ctx,
 				debugEnabled,
@@ -85,7 +133,7 @@ export default function mustHaveExtension(pi: ExtensionAPI): void {
 		}
 
 		if (loaded.source === "legacy_opencode") {
-			warnOnce(
+			await warnOnce(
 				`${EXTENSION_NAME}: using legacy config ${LEGACY_OPENCODE_CONFIG_PATH}. Move it to ${CONFIG_PATH}.`,
 				ctx,
 				debugEnabled,
@@ -94,7 +142,7 @@ export default function mustHaveExtension(pi: ExtensionAPI): void {
 
 		if (debugEnabled) {
 			const replacementCount = Object.keys(loaded.config.replacements).length;
-			writeDebugLog(true, "debug.enabled", {
+			await writeDebugLogWhenEnabled(true, "debug.enabled", {
 				source: loaded.source,
 				replacementCount,
 				configPath: CONFIG_PATH,
@@ -111,9 +159,10 @@ export default function mustHaveExtension(pi: ExtensionAPI): void {
 			return { action: "continue" as const };
 		}
 
+		const { loadConfig } = await loadConfigLoaderModule();
 		const loaded = loadConfig();
 		if (loaded.warning) {
-			warnOnce(loaded.warning, ctx, loaded.config.debug);
+			await warnOnce(loaded.warning, ctx, loaded.config.debug);
 		}
 
 		const replacements = loaded.config.replacements;
@@ -130,7 +179,7 @@ export default function mustHaveExtension(pi: ExtensionAPI): void {
 			const totalReplacements = Array.from(counts.values()).reduce((sum, count) => sum + count, 0);
 			const details = buildReplacementDebugDetails(counts, replacements);
 			const summary = `${EXTENSION_NAME}: applied ${totalReplacements} replacement(s).`;
-			writeDebugLog(true, "replacements.applied", {
+			await writeDebugLogWhenEnabled(true, "replacements.applied", {
 				summary,
 				replacements: details,
 			});