From 7e0cedaebbb77527b51c10c00f3ab979e11c0fee Mon Sep 17 00:00:00 2001
From: Ben Dwyer <ben@scruffian.com>
Date: Thu, 5 Mar 2026 21:06:10 +0000
Subject: [PATCH 1/2] Dev: Auto-clean TypeScript types when switching branches

Automatically detect branch switches via git HEAD and run `npm run clean:package-types` before the TypeScript build. This prevents stale type artifacts from causing compilation errors when moving between branches.

The `headTracker` compares the current git HEAD with a saved `.dev-head` marker file. If they differ, TypeScript declarations are cleaned and rebuilt, ensuring type definitions match the current source code.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
---
 .gitignore  |  1 +
 bin/dev.mjs | 56 +++++++++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 57 insertions(+)

diff --git a/.gitignore b/.gitignore
index 2278f2afa61882..281df86c8fffb8 100644
--- a/.gitignore
+++ b/.gitignore
@@ -12,6 +12,7 @@ coverage
 .phpunit.result.cache
 .reassure
 .dev-ready
+.dev-head
 
 
 # Directories/files that may appear in your environment
diff --git a/bin/dev.mjs b/bin/dev.mjs
index be93ac140d7f33..ec3dd570d53626 100755
--- a/bin/dev.mjs
+++ b/bin/dev.mjs
@@ -110,6 +110,48 @@ const readyMarkerFile = {
 	},
 };
 
+/**
+ * Track the git HEAD to detect branch switches.
+ * Stale TypeScript declaration files from a previous branch cause build
+ * errors, so we clean them automatically when the HEAD changes.
+ */
+const headTracker = {
+	markerPath: path.join( ROOT_DIR, '.dev-head' ),
+	getCurrentHead() {
+		try {
+			return fs
+				.readFileSync(
+					path.join( ROOT_DIR, '.git', 'HEAD' ),
+					'utf8'
+				)
+				.trim();
+		} catch {
+			return null;
+		}
+	},
+	hasChanged() {
+		const currentHead = this.getCurrentHead();
+		if ( ! currentHead ) {
+			return false;
+		}
+		try {
+			const previousHead = fs
+				.readFileSync( this.markerPath, 'utf8' )
+				.trim();
+			return currentHead !== previousHead;
+		} catch {
+			// No marker file means first run — no need to clean.
+			return false;
+		}
+	},
+	save() {
+		const currentHead = this.getCurrentHead();
+		if ( currentHead ) {
+			fs.writeFileSync( this.markerPath, currentHead );
+		}
+	},
+};
+
 /**
  * Main dev orchestration function.
  */
@@ -126,6 +168,17 @@ async function dev() {
 		console.log( '🧹 Cleaning packages...' );
 		await exec( 'npm', [ 'run', 'clean:packages' ], { silent: true } );
 
+		// Step 1.5: Clean TypeScript types if git HEAD changed (e.g. branch switch).
+		// Stale build-types from a previous branch cause compilation errors.
+		if ( headTracker.hasChanged() ) {
+			console.log(
+				'\n🔄 Branch change detected — cleaning TypeScript types...'
+			);
+			await exec( 'npm', [ 'run', 'clean:package-types' ], {
+				silent: true,
+			} );
+		}
+
 		// Step 2: Build workspaces
 		console.log( '\n📦 Building workspaces...' );
 		await exec(
@@ -156,6 +209,9 @@ async function dev() {
 			throw new Error( 'TypeScript compilation failed' );
 		} );
 
+		// Save current HEAD so next run can detect branch switches.
+		headTracker.save();
+
 		// Step 5: Check build type declaration files
 		console.log( '\n✅ Checking type declaration files...' );
 		await exec( 'node', [

From 827c3b670249eb71de9603a2061b3889f26f263d Mon Sep 17 00:00:00 2001
From: Ben Dwyer <ben@scruffian.com>
Date: Fri, 6 Mar 2026 13:14:19 +0000
Subject: [PATCH 2/2] Fix prettier formatting in dev.mjs

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
---
 bin/dev.mjs | 5 +----
 1 file changed, 1 insertion(+), 4 deletions(-)

diff --git a/bin/dev.mjs b/bin/dev.mjs
index ec3dd570d53626..87cc1fdba00bc8 100755
--- a/bin/dev.mjs
+++ b/bin/dev.mjs
@@ -120,10 +120,7 @@ const headTracker = {
 	getCurrentHead() {
 		try {
 			return fs
-				.readFileSync(
-					path.join( ROOT_DIR, '.git', 'HEAD' ),
-					'utf8'
-				)
+				.readFileSync( path.join( ROOT_DIR, '.git', 'HEAD' ), 'utf8' )
 				.trim();
 		} catch {
 			return null;