Add Cursor rules for PowerShell scripts

.cursorrules → .cursor/rules/bash_scripts.mdc

@@ -1,3 +1,7 @@
+---
+description: Standards and Rules to follow when editing bash scripts in @bin/
+globs: bin/*
+---
 # Shell Script Documentation and Standards
 
 ## Shell Script Standards
@@ -37,10 +41,11 @@ For all bash shell scripts, avoid using:
 
 ## Documentation Requirements
 
-When editing or creating files in `/bin`:
+When editing or creating files:
 - Every shell script must have comprehensive header documentation
 - Documentation must include: description, usage, parameters, examples
 - For complex logic, provide detailed examples of different use cases
+- Use backticks (`) around command names, executables, and technical terms in documentation
 - Document all return values and exit codes
 - Keep documentation up to date with any changes
 
@@ -83,7 +88,7 @@ When editing or creating files in `/bin`:
 
 - Use POSIX-compliant syntax and commands
 - Ensure the script is at least compatible with macOS and Linux
-- Make your best effort to make the bash scripts also compatible with Windows if possible, in addition to macOS and Linux. If it's not possible, document that in the script's header documentation
+- Make your best effort to make the bash scripts also compatible with Windows if possible, in addition to macOS and Linux. If it's not possible, document that in the script's header documentation, and, if the features handled by the bash script would be useful and make sense for use cases where we'd still need a Windows agent, propose your help to the author of the original script to create a PowerShell counterpart of that script to provide the same functionality for when running on Windows agents.
 - If the script would behave differently on different platforms despite your best efforts to make it behave the same way cross-platform, document any such platform-specific behavior in the script header documentation
 
 ### For bash scripts compatible with macOS and Linux

.cursor/rules/context.mdc

@@ -0,0 +1,11 @@
+---
+description: Provide context to the agent about this repository and how its files are used
+globs: 
+---
+# Context
+
+- You are a senior software engineer working at Automattic, and you are part of the Apps Infra team, responsible for our CI infrastructure, including providing tools and scripts to run on our CI agents.
+- You are responsible for maintaining and improving the scripts in this repository.
+- Our CI runs on Buildkite infrastructure, using a mix of self-hosted agents (MacMinis in our DataCenter) and Linux or Windows EC2 instances on AWS.
+- This repository contains a collection of bash and PowerShell scripts that are used on our CI agents to help build native iOS and Mac apps, Android apps, and cross-platform Electron apps for desktop environments.
+- Those scripts are made available in our CI agents via the Buildkite plugin system. The scripts in the `bin/` directory are available in the `$PATH` of all our CI jobs that use `a8c-ci-toolkit` in their pipeline steps' `plugins:` attribute.

.cursor/rules/powershell_scripts.mdc

@@ -0,0 +1,141 @@
+---
+description: Standards and Rules to follow when editing PowerShell scripts in @bin/
+globs: *.ps1
+---
+# PowerShell Script Documentation and Standards
+
+## PowerShell Script Standards
+
+For all PowerShell scripts:
+- Ensure compatibility with Windows PowerShell 5.1 (default on Windows Server)
+- Follow `PSScriptAnalyzer` recommendations
+- Use proper error handling and input validation
+- Use UTF-8 encoding without BOM for script files
+- Document Windows-specific requirements and dependencies
+
+## Best Practices
+
+For all PowerShell scripts:
+- Use `$ErrorActionPreference = "Stop"` at the beginning of scripts
+- Use `Set-StrictMode -Version Latest` for strict variable and function checking
+- Always use full cmdlet names (avoid aliases like `ls`, use `Get-ChildItem` instead)
+- Use proper verb-noun naming convention for functions
+- Quote all variable expansions in strings
+- Use `[CmdletBinding()]` for advanced functions
+- Use parameter validation attributes
+- Include proper error handling with try/catch blocks
+- Use approved PowerShell verbs (Get-Verb)
+- End script files with a newline
+- Use proper PowerShell case conventions:
+  - PascalCase for functions, cmdlets, and parameters
+  - camelCase for variables
+  - UPPERCASE for constants
+- Check for and require Administrator privileges when needed using:
+
+```powershell
+if (-not ([Security.Principal.WindowsPrincipal] [Security.Principal.WindowsIdentity]::GetCurrent()).IsInRole([Security.Principal.WindowsBuiltinRole]::Administrator)) {
+  throw "This script requires Administrator privileges"
+}
+```
+
+## Documentation Requirements
+
+When editing or creating PowerShell scripts in `/bin`:
+- Every script must have comprehensive comment-based help
+- Documentation must include: synopsis, description, parameters, examples
+- For complex logic, provide detailed examples of different use cases
+- Use backticks (`) around command names, executables, and technical terms in documentation
+- Document all return values and terminating conditions
+- Keep documentation up to date with any changes
+- Clearly document Windows version requirements or limitations
+- Document required Windows features or roles
+
+## Documentation Template
+
+```powershell
+<#
+.SYNOPSIS
+    Brief description of what the script does.
+
+.DESCRIPTION
+    Detailed description of the script's purpose and functionality.
+
+.PARAMETER ParameterName
+    Description of each parameter.
+
+.EXAMPLE
+    Example-1
+    Detailed description of the example.
+
+.NOTES
+    Author: [Author name]
+    Last Edit: [Date]
+    Version 1.0 - Initial release
+    Requirements: Windows PowerShell 5.1
+    Windows Requirements:
+        - Windows Server 2019 or later
+        - Required Windows Features: [list features]
+        - Required Windows Roles: [list roles]
+        - Administrator privileges: [Yes/No]
+
+.OUTPUTS
+    Description of the script's output.
+
+.RETURNVALUES
+    Description of possible return values and their meanings.
+#>
+```
+
+## Windows-Specific Best Practices
+
+### Registry Operations
+- Always use try/catch blocks when modifying registry
+- Use proper registry paths (HKLM:\ instead of HKEY_LOCAL_MACHINE)
+- Check registry key existence before operations
+- Document any registry modifications in script header
+
+### Windows Services
+- Use proper error handling for service operations
+- Check service status before operations
+- Handle service dependencies
+- Document required service account privileges
+
+### File System Operations
+- Use proper path handling for Windows paths
+- Handle long path limitations appropriately
+- Use proper file system permissions checks
+- Handle file locks and sharing violations
+
+### Windows Features and Roles
+- Document required Windows features
+- Check feature presence before operations
+- Handle feature installation failures
+- Document minimum Windows version requirements
+
+### Required PowerShell Modules
+
+For any PowerShell script that needs additional modules:
+- Document required modules in the script's help section
+- Use `#Requires -Modules` statements at the start of the script
+- Include minimum version requirements if specific versions are needed
+- Document any Windows-specific module dependencies
+
+## Script Validation
+
+Before committing PowerShell scripts, ensure:
+- PSScriptAnalyzer passes with no warnings
+- Comment-based help is complete
+- Windows requirements are documented
+- All functions have proper error handling
+- Variables are properly scoped
+- Parameters are properly validated
+- Administrator requirements are documented and checked if needed
+
+## PowerShell Compatibility
+
+For all PowerShell scripts, avoid using:
+- PowerShell 7.x exclusive features
+- Deprecated cmdlets and parameters
+- Write-Host (use Write-Output or Write-Information instead)
+- Positional parameters (always use named parameters)
+- Global variables without explicit scope declaration