@narumitw/pi-chrome-devtools 0.11.0 → 0.12.0

package/README.md

@@ -164,13 +164,19 @@ Direct subcommands are also available:
 The selected tool names are saved to:
 
 ```text
-${PI_CODING_AGENT_DIR:-~/.pi/agent}/pi-chrome-devtools-settings.json
+${PI_CODING_AGENT_DIR:-~/.pi/agent}/pi-chrome-devtools.json
 ```
 
 When the file is missing or invalid, the extension preserves Pi's current active-tool policy
 instead of enabling tools by itself. A valid saved selection is restored on Pi startup and
 `/reload`.
 
+Compatibility: older versions used `pi-chrome-devtools-settings.json`. During the migration
+window, a legacy-only file is automatically migrated to `pi-chrome-devtools.json` with a warning.
+If both files exist, `pi-chrome-devtools.json` wins and the legacy file is ignored. The legacy
+filename is deprecated and planned for removal after at least one minor release cycle, preferably
+4–8 weeks, or at the next major release.
+
 ## 🧠 Use cases
 
 - Debug front-end applications with an AI coding agent.

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@narumitw/pi-chrome-devtools",
-	"version": "0.11.0",
+	"version": "0.12.0",
 	"description": "Pi extension that exposes Chrome DevTools Protocol tools.",
 	"type": "module",
 	"license": "MIT",

package/src/chrome-devtools.ts

@@ -1,7 +1,7 @@
 import { spawn, type ChildProcess } from "node:child_process";
 import { randomUUID } from "node:crypto";
 import { constants } from "node:fs";
-import { access, lstat, mkdir, mkdtemp, readFile, realpath, rename, rm, writeFile } from "node:fs/promises";
+import { access, link, lstat, mkdir, mkdtemp, readFile, realpath, rename, rm, writeFile } from "node:fs/promises";
 import { homedir, tmpdir } from "node:os";
 import { basename, delimiter, dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
 import {
@@ -24,10 +24,8 @@ const MANAGED_BROWSER_PROFILE_PREFIX = "pi-chrome-devtools-profile-";
 const DEVTOOLS_ACTIVE_PORT_FILE = "DevToolsActivePort";
 const BROWSER_SHUTDOWN_WAIT_MS = 1_500;
 const STATUS_KEY = "chrome-devtools";
-const SETTINGS_FILE = join(
-	process.env.PI_CODING_AGENT_DIR ?? join(homedir(), ".pi", "agent"),
-	"pi-chrome-devtools-settings.json",
-);
+const NEW_SETTINGS_FILE_NAME = "pi-chrome-devtools.json";
+const LEGACY_SETTINGS_FILE_NAME = "pi-chrome-devtools-settings.json";
 const CHROME_DEVTOOLS_TOOL_NAMES = [
 	"chrome_devtools_list_pages",
 	"chrome_devtools_select_page",
@@ -108,6 +106,7 @@ interface ChromeDevToolsState {
 	launchPromise?: Promise<void>;
 	lastLaunchAttempt?: BrowserLaunchAttempt;
 	shuttingDown: boolean;
+	settingsNotice?: string;
 }
 
 interface ManagedBrowser {
@@ -375,8 +374,11 @@ export default function chromeDevtools(pi: ExtensionAPI) {
 
 	pi.on("session_start", async (_event, ctx) => {
 		state.shuttingDown = false;
+		state.settingsNotice = undefined;
 		ctx.ui.setStatus(STATUS_KEY, undefined);
 		const settings = await loadSettings();
+		recordSettingsNotice(settings);
+		if (settings.notice) ctx.ui.notify(settings.notice, "warning");
 		if (settings.kind === "loaded") {
 			applyChromeDevtoolsTools(pi, settings.settings.tools);
 			return;
@@ -670,7 +672,8 @@ async function buildToolStatusMessage(pi: ExtensionAPI) {
 	return [
 		`Chrome DevTools tools: ${formatRuntimeStatus(summary)}`,
 		`Persisted selection: ${persistedSetting}`,
-		`Settings file: ${SETTINGS_FILE}`,
+		`Settings file: ${settingsFilePath()}`,
+		...(state.settingsNotice ? [`Settings note: ${state.settingsNotice}`] : []),
 		`Other active tools preserved: ${summary.activeNonChromeToolCount}`,
 		`Endpoint: ${devToolsEndpoint()}`,
 		`Endpoint source: ${endpointSourceLabel()}`,
@@ -745,6 +748,7 @@ function formatRuntimeStatus(summary: ToolStatusSummary) {
 
 async function persistedSettingLabel() {
 	const settings = await loadSettings();
+	recordSettingsNotice(settings);
 	if (settings.kind === "loaded") return formatPersistedSelection(settings.settings.tools);
 	if (settings.kind === "invalid") {
 		return `none; current active-tool policy preserved (invalid settings ignored: ${settings.reason})`;
@@ -771,29 +775,129 @@ async function persistSettings(
 	}
 }
 
-async function loadSettings(): Promise<
-	| { kind: "missing" }
-	| { kind: "invalid"; reason: string }
-	| { kind: "loaded"; settings: ChromeDevToolsSettings }
-> {
+type SettingsLoadResult =
+	| { kind: "missing"; notice?: string }
+	| { kind: "invalid"; reason: string; notice?: string }
+	| { kind: "loaded"; settings: ChromeDevToolsSettings; notice?: string };
+
+type SettingsMigrationResult = {
+	kind: "migrated" | "failed";
+	notice: string;
+};
+
+async function loadSettings(): Promise<SettingsLoadResult> {
+	const newPath = settingsFilePath();
+	const newSettings = await readSettingsFile(newPath);
+	if (newSettings.kind !== "missing") {
+		return withLegacyIgnoredNotice(newSettings);
+	}
+
+	const legacyPath = legacySettingsFilePath();
+	const legacySettings = await readSettingsFile(legacyPath);
+	const concurrentlyCreatedSettings = await readSettingsFile(newPath);
+	if (concurrentlyCreatedSettings.kind !== "missing") {
+		return withLegacyIgnoredNotice(concurrentlyCreatedSettings);
+	}
+	if (legacySettings.kind === "missing") return { kind: "missing" };
+	if (legacySettings.kind === "invalid") return legacySettings;
+
+	const migration = await migrateLegacySettings(legacyPath, legacySettings.settings);
+	if (migration.kind === "failed") {
+		const settingsCreatedDuringMigration = await readSettingsFile(newPath);
+		if (settingsCreatedDuringMigration.kind !== "missing") {
+			return withLegacyIgnoredNotice(settingsCreatedDuringMigration);
+		}
+	}
+
+	return { ...legacySettings, notice: migration.notice };
+}
+
+async function readSettingsFile(filePath: string): Promise<SettingsLoadResult> {
 	let text: string;
 	try {
-		text = await readFile(SETTINGS_FILE, "utf8");
+		text = await readFile(filePath, "utf8");
 	} catch (error) {
 		if (isNodeError(error) && error.code === "ENOENT") return { kind: "missing" };
-		return { kind: "invalid", reason: formatError(error) };
+		return { kind: "invalid", reason: `${filePath}: ${formatError(error)}` };
 	}
 
 	try {
 		const parsed = JSON.parse(text) as unknown;
 		const settings = normalizeChromeDevtoolsSettings(parsed);
 		if (settings) return { kind: "loaded", settings };
-		return { kind: "invalid", reason: "expected tools to be an array of Chrome DevTools tool names" };
+		return {
+			kind: "invalid",
+			reason: `${filePath}: expected tools to be an array of Chrome DevTools tool names`,
+		};
+	} catch (error) {
+		return { kind: "invalid", reason: `${filePath}: ${formatError(error)}` };
+	}
+}
+
+async function withLegacyIgnoredNotice(settings: SettingsLoadResult): Promise<SettingsLoadResult> {
+	if (!(await fileExists(legacySettingsFilePath()))) return settings;
+	return {
+		...settings,
+		notice: `Chrome DevTools legacy settings ignored: ${legacySettingsFilePath()} exists, but ${settingsFilePath()} takes precedence. Delete ${LEGACY_SETTINGS_FILE_NAME} after confirming your settings.`,
+	};
+}
+
+export async function installSettingsFileExclusively(filePath: string, contents: string) {
+	await mkdir(dirname(filePath), { recursive: true });
+	const tempFile = `${filePath}.${process.pid}.${randomUUID()}.tmp`;
+	try {
+		await writeFile(tempFile, contents, { encoding: "utf8", flag: "wx" });
+		await link(tempFile, filePath);
+	} finally {
+		await rm(tempFile, { force: true }).catch(() => undefined);
+	}
+}
+
+async function migrateLegacySettings(
+	legacyPath: string,
+	settings: ChromeDevToolsSettings,
+): Promise<SettingsMigrationResult> {
+	const newPath = settingsFilePath();
+	try {
+		await installSettingsFileExclusively(
+			newPath,
+			`${JSON.stringify(settings, null, 2)}\n`,
+		);
+	} catch (error) {
+		return {
+			kind: "failed",
+			notice: `Chrome DevTools legacy settings migration failed: could not migrate ${legacyPath} to ${newPath}: ${formatError(error)}. The legacy file was used for this session; future saves will write ${NEW_SETTINGS_FILE_NAME}.`,
+		};
+	}
+
+	try {
+		await rm(legacyPath, { force: true });
 	} catch (error) {
-		return { kind: "invalid", reason: formatError(error) };
+		return {
+			kind: "migrated",
+			notice: `Chrome DevTools settings migrated from ${legacyPath} to ${newPath}, but the legacy file could not be removed: ${formatError(error)}. Delete ${LEGACY_SETTINGS_FILE_NAME} after confirming your settings.`,
+		};
+	}
+
+	return {
+		kind: "migrated",
+		notice: `Chrome DevTools settings migrated from ${legacyPath} to ${newPath}. ${LEGACY_SETTINGS_FILE_NAME} is deprecated and will be removed in a future major release.`,
+	};
+}
+
+async function fileExists(filePath: string) {
+	try {
+		await access(filePath, constants.F_OK);
+		return true;
+	} catch {
+		return false;
 	}
 }
 
+function recordSettingsNotice(settings: SettingsLoadResult) {
+	if (settings.notice) state.settingsNotice = settings.notice;
+}
+
 export function normalizeChromeDevtoolsSettings(value: unknown): ChromeDevToolsSettings | undefined {
 	if (!value || typeof value !== "object") return undefined;
 	const settings = value as { tools?: unknown; updatedAt?: unknown };
@@ -819,18 +923,30 @@ function orderedUniqueChromeDevtoolsTools(tools: readonly ChromeDevToolsToolName
 }
 
 async function saveSettings(settings: ChromeDevToolsSettings) {
-	await mkdir(dirname(SETTINGS_FILE), { recursive: true });
-	const tempFile = `${SETTINGS_FILE}.${process.pid}.${Date.now()}.tmp`;
+	const filePath = settingsFilePath();
+	await mkdir(dirname(filePath), { recursive: true });
+	const tempFile = `${filePath}.${process.pid}.${Date.now()}.tmp`;
 	try {
-		await writeFile(tempFile, `${JSON.stringify(settings, null, 2)}
-`, "utf8");
-		await rename(tempFile, SETTINGS_FILE);
+		await writeFile(tempFile, `${JSON.stringify(settings, null, 2)}\n`, "utf8");
+		await rename(tempFile, filePath);
 	} catch (error) {
 		await rm(tempFile, { force: true }).catch(() => undefined);
 		throw error;
 	}
 }
 
+function settingsFilePath() {
+	return join(agentDir(), NEW_SETTINGS_FILE_NAME);
+}
+
+function legacySettingsFilePath() {
+	return join(agentDir(), LEGACY_SETTINGS_FILE_NAME);
+}
+
+function agentDir() {
+	return process.env.PI_CODING_AGENT_DIR ?? join(homedir(), ".pi", "agent");
+}
+
 function isNodeError(error: unknown): error is NodeJS.ErrnoException {
 	return error instanceof Error && "code" in error;
 }