Add Node.js version checking and enhanced Copilot setup instructions

Co-authored-by: rebornix <876920+rebornix@users.noreply.github.com>

Author: Copilot

CONTRIBUTING.md

@@ -67,16 +67,65 @@ Please include the following with each issue:
 # Developing
 
 ## Requirements
-- Node 22.x
+- **Node.js 22.14.0 or higher** (see [Node Version](#node-version-management) below)
+- **npm 9.0.0 or higher**
 - Python >= 3.10, <= 3.12
 - Git Large File Storage (LFS) - for running tests
 - (Windows) Visual Studio Build Tools >=2019 - for building with node-gyp [see node-gyp docs](https://github.com/nodejs/node-gyp?tab=readme-ov-file#on-windows)
 
+### Node Version Management
+
+This project requires Node.js 22.14.0 or higher. The exact version used by the project is specified in `.nvmrc`.
+
+**Using Node Version Manager (nvm) - Recommended:**
+```bash
+# Install and use the correct Node.js version
+nvm install 22.15.1
+nvm use 22.15.1
+
+# Verify version
+node --version  # should show v22.15.1 or higher
+```
+
+**Manual Installation:**
+Download Node.js 22.x from [nodejs.org](https://nodejs.org/) if you prefer not to use nvm.
+
+### Copilot Agent Environment Setup
+
+This extension works with GitHub Copilot agents and requires proper authentication and environment configuration. Follow these steps for agent environment customization:
+
+1. **GitHub Authentication**: Ensure you have access to GitHub Copilot
+2. **Development Token**: Run `npm run get_token` to set up your development OAuth token
+3. **Environment Variables**: Run `npm run get_env` to configure additional secrets (for Microsoft team members)
+
+For more details on customizing the Copilot agent environment, see the [GitHub Copilot documentation](https://docs.github.com/en/copilot/how-tos/use-copilot-agents/coding-agent/customize-the-agent-environment).
+
 ### First-time setup
-- on Windows you need to run `Set-ExecutionPolicy Unrestricted` as admin in Powershell.
-- `npm install`
-- `npm run get_token`
-- Then you can run the build task with `cmd+shift+B`, or just start the "Launch Copilot Extension - Watch Mode" launch config to start the build then start debugging the extension.
+1. **Check Prerequisites**: Verify your development environment meets the requirements
+   ```bash
+   # Check Node.js and npm versions
+   npm run check-env
+   ```
+
+2. **Windows Setup**: On Windows, run `Set-ExecutionPolicy Unrestricted` as admin in Powershell.
+
+3. **Install Dependencies**: 
+   ```bash
+   npm install
+   ```
+
+4. **Authentication Setup**:
+   ```bash
+   # Set up GitHub OAuth token for development
+   npm run get_token
+   
+   # (Microsoft team members only) Set up additional environment variables
+   npm run get_env
+   ```
+
+5. **Start Development**: 
+   - Use VS Code's build task: `Ctrl+Shift+P` → "Tasks: Run Build Task" 
+   - Or start the "Launch Copilot Extension - Watch Mode" launch config to build and debug the extension
 
 **Tip:** If "Launch Copilot Extension - Watch Mode" doesn't work for you, try using the "Launch Copilot Extension" debug configuration instead.
 

README.md

@@ -68,6 +68,33 @@ To get the latest security fixes, please use the latest version of the Copilot e
 * **[FAQ](https://code.visualstudio.com/docs/copilot/faq)**
 * **[Feedback](https://github.com/microsoft/vscode-copilot-release/issues)**: We'd love to get your help in making GitHub Copilot better!
 
+## Development Setup
+
+Interested in contributing to the GitHub Copilot Chat extension? Get started with development:
+
+### Prerequisites
+- **Node.js 22.14.0+**: Required for building and running the extension
+- **GitHub Copilot Access**: Needed for testing and development
+- **Git LFS**: Required for accessing test fixtures and large files
+
+### Quick Start
+```bash
+# Check your development environment
+npm run check-env
+
+# Install dependencies and set up authentication
+npm run setup
+
+# Start development in VS Code
+# Use "Launch Copilot Extension - Watch Mode" debug configuration
+```
+
+### Detailed Instructions
+For comprehensive setup instructions, development guidelines, and contribution information, see [CONTRIBUTING.md](CONTRIBUTING.md).
+
+### Customizing the Agent Environment
+Learn about customizing GitHub Copilot agents for your development workflow in the [GitHub documentation](https://docs.github.com/en/copilot/how-tos/use-copilot-agents/coding-agent/customize-the-agent-environment).
+
 ## Data and telemetry
 
 The GitHub Copilot Extension for Visual Studio Code collects usage data and sends it to Microsoft to help improve our products and services. Read our [privacy statement](https://privacy.microsoft.com/privacystatement) to learn more. This extension respects the `telemetry.telemetryLevel` setting which you can learn more about at https://code.visualstudio.com/docs/supporting/faq#_how-to-disable-telemetry-reporting.

package.json

@@ -3936,6 +3936,7 @@
 		"singleQuote": true
 	},
 	"scripts": {
+		"check-env": "node ./script/setup/checkNodeVersion.js",
 		"postinstall": "tsx ./script/postinstall.ts",
 		"prepare": "husky",
 		"vscode-dts:dev": "node node_modules/@vscode/dts/index.js dev && mv vscode.proposed.*.ts src/extension",
@@ -3965,7 +3966,7 @@
 		"simulate-ci": "node dist/simulationMain.js --ci --require-cache",
 		"simulate-update-baseline": "node dist/simulationMain.js --update-baseline",
 		"simulate-gc": "node dist/simulationMain.js --require-cache --gc",
-		"setup": "npm run get_env && npm run get_token",
+		"setup": "npm run check-env && npm run get_env && npm run get_token",
 		"setup:dotnet": "run-script-os",
 		"setup:dotnet:darwin:linux": "curl -O https://raw.githubusercontent.com/dotnet/install-scripts/main/src/dotnet-install.sh && chmod u+x dotnet-install.sh && ./dotnet-install.sh --channel 10.0 && rm dotnet-install.sh",
 		"setup:dotnet:win32": "powershell.exe -NoProfile -ExecutionPolicy Bypass -Command \"Invoke-WebRequest -Uri https://raw.githubusercontent.com/dotnet/install-scripts/main/src/dotnet-install.ps1 -OutFile dotnet-install.ps1; ./dotnet-install.ps1 -channel 10.0; Remove-Item dotnet-install.ps1\"",

script/postinstall.ts

@@ -6,9 +6,46 @@
 import { downloadZMQ } from '@vscode/zeromq';
 import * as fs from 'fs';
 import * as path from 'path';
+import { execSync } from 'child_process';
 import { compressTikToken } from './build/compressTikToken';
 import { copyStaticAssets } from './build/copyStaticAssets';
 
+// Check Node.js version before proceeding
+function checkNodeVersion(): void {
+	const packageJsonPath = path.join(__dirname, 'package.json');
+	const packageJson = JSON.parse(fs.readFileSync(packageJsonPath, 'utf8'));
+	
+	const requiredNodeVersion = packageJson.engines?.node;
+	if (!requiredNodeVersion) {
+		return;
+	}
+	
+	const currentNodeVersion = process.version;
+	const currentVersion = currentNodeVersion.slice(1);
+	
+	const requiredMatch = requiredNodeVersion.match(/>=(\d+)\.(\d+)\.(\d+)/);
+	if (!requiredMatch) {
+		return;
+	}
+	
+	const [, reqMajor, reqMinor, reqPatch] = requiredMatch.map(Number);
+	const [currentMajor, currentMinor, currentPatch] = currentVersion.split('.').map(Number);
+	
+	const isVersionValid = 
+		currentMajor > reqMajor || 
+		(currentMajor === reqMajor && currentMinor > reqMinor) ||
+		(currentMajor === reqMajor && currentMinor === reqMinor && currentPatch >= reqPatch);
+	
+	if (!isVersionValid) {
+		console.error('\n❌ Node.js version requirement not met!');
+		console.error(`Required: ${requiredNodeVersion}`);
+		console.error(`Current:  ${currentNodeVersion}`);
+		console.error('\nPlease upgrade your Node.js version.');
+		console.error('Run: npm run check-env for detailed instructions.');
+		process.exit(1);
+	}
+}
+
 export interface ITreeSitterGrammar {
 	name: string;
 	/**
@@ -63,6 +100,9 @@ const treeSitterGrammars: ITreeSitterGrammar[] = [
 const REPO_ROOT = path.join(__dirname, '..');
 
 async function main() {
+	// Check Node.js version before starting
+	checkNodeVersion();
+	
 	await fs.promises.mkdir(path.join(REPO_ROOT, '.build'), { recursive: true });
 
 	const vendoredTiktokenFiles = ['src/platform/tokenizer/node/cl100k_base.tiktoken', 'src/platform/tokenizer/node/o200k_base.tiktoken'];

script/setup/checkNodeVersion.js

@@ -0,0 +1,148 @@
+/*---------------------------------------------------------------------------------------------
+ *  Copyright (c) Microsoft Corporation. All rights reserved.
+ *  Licensed under the MIT License. See License.txt in the project root for license information.
+ *--------------------------------------------------------------------------------------------*/
+
+const fs = require('fs');
+const path = require('path');
+const { execSync } = require('child_process');
+
+/**
+ * Check if the current Node.js version meets the project requirements
+ */
+function checkNodeVersion() {
+	const packageJsonPath = path.join(__dirname, '../../package.json');
+	const packageJson = JSON.parse(fs.readFileSync(packageJsonPath, 'utf8'));
+	
+	const requiredNodeVersion = packageJson.engines?.node;
+	if (!requiredNodeVersion) {
+		console.log('No Node.js version requirement found in package.json');
+		return;
+	}
+	
+	const currentNodeVersion = process.version;
+	console.log(`Current Node.js version: ${currentNodeVersion}`);
+	console.log(`Required Node.js version: ${requiredNodeVersion}`);
+	
+	// Extract version number (remove 'v' prefix)
+	const currentVersion = currentNodeVersion.slice(1);
+	
+	// Simple version check for >=22.14.0 format
+	const requiredMatch = requiredNodeVersion.match(/>=(\d+)\.(\d+)\.(\d+)/);
+	if (!requiredMatch) {
+		console.warn('Could not parse required Node.js version format');
+		return;
+	}
+	
+	const [, reqMajor, reqMinor, reqPatch] = requiredMatch.map(Number);
+	const [currentMajor, currentMinor, currentPatch] = currentVersion.split('.').map(Number);
+	
+	const isVersionValid = 
+		currentMajor > reqMajor || 
+		(currentMajor === reqMajor && currentMinor > reqMinor) ||
+		(currentMajor === reqMajor && currentMinor === reqMinor && currentPatch >= reqPatch);
+	
+	if (!isVersionValid) {
+		console.error('\n❌ Node.js version requirement not met!');
+		console.error(`Required: ${requiredNodeVersion}`);
+		console.error(`Current:  ${currentNodeVersion}`);
+		console.error('\nPlease upgrade your Node.js version to continue.');
+		console.error('\n📋 Installation Options:');
+		console.error('\n1. Using Node Version Manager (nvm) - Recommended:');
+		console.error('   nvm install 22.15.1');
+		console.error('   nvm use 22.15.1');
+		console.error('\n2. Manual installation:');
+		console.error('   Download from: https://nodejs.org/');
+		console.error('   Install Node.js 22.x or higher');
+		console.error('\n3. Using package managers:');
+		console.error('   # Using Homebrew (macOS)');
+		console.error('   brew install node@22');
+		console.error('   # Using winget (Windows)');
+		console.error('   winget install OpenJS.NodeJS');
+		console.error('\nAfter installation, restart your terminal and try again.');
+		process.exit(1);
+	}
+	
+	console.log('✅ Node.js version requirement satisfied');
+}
+
+/**
+ * Check if the current npm version meets the project requirements
+ */
+function checkNpmVersion() {
+	const packageJsonPath = path.join(__dirname, '../../package.json');
+	const packageJson = JSON.parse(fs.readFileSync(packageJsonPath, 'utf8'));
+	
+	const requiredNpmVersion = packageJson.engines?.npm;
+	if (!requiredNpmVersion) {
+		return;
+	}
+	
+	try {
+		const currentNpmVersion = execSync('npm --version', { encoding: 'utf8' }).trim();
+		console.log(`Current npm version: ${currentNpmVersion}`);
+		console.log(`Required npm version: ${requiredNpmVersion}`);
+		
+		// Simple check for >=9.0.0 format
+		const requiredMatch = requiredNpmVersion.match(/>=(\d+)\.(\d+)\.(\d+)/);
+		if (!requiredMatch) {
+			console.warn('Could not parse required npm version format');
+			return;
+		}
+		
+		const [, reqMajor] = requiredMatch.map(Number);
+		const [currentMajor] = currentNpmVersion.split('.').map(Number);
+		
+		if (currentMajor >= reqMajor) {
+			console.log('✅ npm version requirement satisfied');
+		} else {
+			console.warn('⚠️  npm version may be outdated');
+			console.warn(`Consider upgrading npm: npm install -g npm@latest`);
+		}
+	} catch (error) {
+		console.warn('Could not check npm version');
+	}
+}
+
+/**
+ * Check for GitHub Copilot setup prerequisites
+ */
+function checkCopilotPrerequisites() {
+	console.log('\n🤖 GitHub Copilot Development Setup:');
+	
+	// Check if .env file exists (for tokens)
+	const envPath = path.join(__dirname, '../../.env');
+	if (fs.existsSync(envPath)) {
+		console.log('✅ .env file found (authentication tokens configured)');
+	} else {
+		console.log('⚠️  .env file not found');
+		console.log('   Run: npm run get_token    # to set up GitHub OAuth token');
+		console.log('   Run: npm run get_env      # (Microsoft team members only)');
+	}
+	
+	// Check for Git LFS
+	try {
+		execSync('git lfs version', { stdio: 'pipe' });
+		console.log('✅ Git LFS is installed');
+	} catch (error) {
+		console.log('❌ Git LFS not found');
+		console.log('   Install from: https://git-lfs.com/');
+		console.log('   Or use package manager: brew install git-lfs / winget install GitHub.GitLFS');
+	}
+	
+	console.log('\n📚 Next Steps:');
+	console.log('1. Sign up for GitHub Copilot: https://github.com/settings/copilot');
+	console.log('2. Read setup guide: https://docs.github.com/en/copilot/how-tos/use-copilot-agents/coding-agent/customize-the-agent-environment');
+	console.log('3. Run: npm run setup     # to complete authentication setup');
+	console.log('4. Start debugging in VS Code with "Launch Copilot Extension - Watch Mode"');
+}
+
+function main() {
+	console.log('🔍 Checking development environment requirements...\n');
+	checkNodeVersion();
+	checkNpmVersion();
+	checkCopilotPrerequisites();
+	console.log('\n✅ Environment check complete!');
+}
+
+main();