chore: auto-version New-Release.ps1 (patch bump from highest tag) & README docs update

Author: dkattan

New-Release.ps1

@@ -3,13 +3,10 @@
 Automates creating a new extension release: prepends release notes to CHANGELOG.md, commits, tags, and creates GitHub release.
 
 .DESCRIPTION
-New-Release.ps1 updates CHANGELOG.md by inserting a new version section right after the Unreleased header, commits the change, creates an annotated tag following v<Major>.<Minor>.<Build>[.<Revision>] pattern, and invokes `gh release create` with the provided notes.
-
-.PARAMETER Version
-System.Version representing the new version. Tag format derives from all numeric components present.
+New-Release.ps1 updates CHANGELOG.md by inserting a new version section right after the Unreleased header, commits the change, determines the next semantic version automatically by inspecting existing git tags (pattern: v<Major>.<Minor>.<Build>[.<Revision>]), creates an annotated tag, and invokes `gh release create` with the provided notes.
 
 .PARAMETER ReleaseNotes
-String containing markdown release notes (can include multiline text). This will be used both for CHANGELOG entry body and GitHub release notes.
+Markdown release notes (multiline supported) used for CHANGELOG body and GitHub release.
 
 .PARAMETER Date
 Optional override for release date (YYYY-MM-DD). Defaults to current UTC date.
@@ -21,17 +18,16 @@ If set, does not push commit/tag to origin.
 If set, shows the changes that would be made without applying them.
 
 .EXAMPLE
-./New-Release.ps1 -Version 0.0.17 -ReleaseNotes "**Added:** New feature X\n**Fixed:** Bug Y"
+./New-Release.ps1 -ReleaseNotes "**Added:** Feature X`n**Fixed:** Bug Y"
 
 .EXAMPLE
-./New-Release.ps1 -Version 1.2.3.4 -ReleaseNotes (Get-Content RELEASE_NOTES_1.2.3.md -Raw)
+$notes = @'\n**Added:** Dashboard refresh\n**Changed:** Improved docs\n'@; ./New-Release.ps1 -ReleaseNotes $notes
 
 .NOTES
-Requires `gh` CLI authenticated for release creation; if missing, script will warn and skip release step.
+Requires `gh` CLI authenticated for release creation; if missing, script will warn and skip release step. Version auto-increment strategy: bump patch (Build component). If no existing tags are found, starts at 0.0.1.
 #>
 [CmdletBinding(SupportsShouldProcess=$true)]
 param(
-    [Parameter(Mandatory=$true)][Version]$Version,
     [Parameter(Mandatory=$true)][string]$ReleaseNotes,
     [string]$Date = (Get-Date -AsUTC -Format 'yyyy-MM-dd'),
     [switch]$SkipGitPush,
@@ -48,7 +44,27 @@ function Get-TagName {
     return 'v' + ($parts -join '.')
 }
 
-function Insert-ChangelogEntry {
+function Get-NextVersion {
+    # Gather existing tags matching v* and parse into System.Version
+    if (-not (Get-Command git -ErrorAction SilentlyContinue)) { throw 'git CLI not available' }
+    $rawTags = (& git tag --list 'v*') 2>$null
+    $versions = @()
+    foreach ($t in $rawTags) {
+        $trim = $t.Trim()
+        if ($trim -match '^v(\d+(?:\.\d+){0,3})$') {
+            $verString = $Matches[1]
+            try { $versions += [Version]$verString } catch { }
+        }
+    }
+    if (-not $versions -or $versions.Count -eq 0) {
+        return [Version]'0.0.1'
+    }
+    $current = $versions | Sort-Object -Descending | Select-Object -First 1
+    $buildComponent = if ($current.Build -ge 0) { $current.Build + 1 } else { 1 }
+    return [Version]::new($current.Major, $current.Minor, $buildComponent)
+}
+
+function Add-ChangelogEntry {
     param(
         [string]$Path,
         [Version]$V,
@@ -58,18 +74,18 @@ function Insert-ChangelogEntry {
     if (-not (Test-Path $Path)) { throw "CHANGELOG file not found: $Path" }
     $content = Get-Content $Path -Raw
     $header = "## [$($V.ToString())] - $Date" + [Environment]::NewLine + [Environment]::NewLine + $Notes.Trim() + [Environment]::NewLine + [Environment]::NewLine
-    # Insert after first occurrence of Unreleased section
     $pattern = "## \[Unreleased\]";
     if ($content -notmatch $pattern) { throw 'Unreleased section marker not found in CHANGELOG.md' }
     $updated = $content -replace $pattern, ($pattern + [Environment]::NewLine + [Environment]::NewLine + $header)
     return $updated
 }
 
+$Version = Get-NextVersion
 $tag = Get-TagName -V $Version
-Write-Host "[info] Target version: $Version (tag: $tag)" -ForegroundColor Cyan
+Write-Host "[info] Auto-detected next version: $Version (tag: $tag)" -ForegroundColor Cyan
 
 $changelogPath = Join-Path $PSScriptRoot 'CHANGELOG.md'
-$newContent = Insert-ChangelogEntry -Path $changelogPath -V $Version -Notes $ReleaseNotes -Date $Date
+$newContent = Add-ChangelogEntry -Path $changelogPath -V $Version -Notes $ReleaseNotes -Date $Date
 
 if ($DryRun) {
     Write-Host "[dry-run] CHANGELOG preview:" -ForegroundColor Yellow

README.md

@@ -201,20 +201,21 @@ Release flow – push tag & create a GitHub release to trigger publish workflow.
 
 ### Automated Release Script
 
-You can automate steps 4–9 with the PowerShell helper `New-Release.ps1`:
+You can automate steps 4–9 with the PowerShell helper `New-Release.ps1` (auto-increments version):
 
 ```powershell
-./New-Release.ps1 -Version 0.0.17 -ReleaseNotes "**Added:** Feature X`n**Fixed:** Issue Y"
+./New-Release.ps1 -ReleaseNotes "**Added:** Feature X`n**Fixed:** Issue Y"
 ```
 
 Parameters:
 
-- `-Version` (System.Version) – New semantic version (e.g., 0.0.17 or 1.2.3.4). Tag generated as `v<Major>.<Minor>.<Build>[.<Revision>]`.
 - `-ReleaseNotes` (string) – Markdown body inserted into CHANGELOG and used for GitHub release notes.
 - `-Date` (optional) – Override date; defaults to current UTC.
 - `-SkipGitPush` – Create commit + tag locally but do not push.
 - `-DryRun` – Show planned changes without applying.
 
+Auto versioning: Script scans existing tags (`git tag --list 'v*'`), parses semantic versions, selects the highest, then increments the patch (Build) component. If no tags exist it starts at `0.0.1`.
+
 Behavior:
 
 1. Prepends a new `## [Version] - Date` section after `## [Unreleased]` in `CHANGELOG.md`.
@@ -231,7 +232,7 @@ $notes = @'
 **Changed:** Improved variable filtering docs
 **Fixed:** Race condition in session start
 '@
-./New-Release.ps1 -Version 0.0.18 -ReleaseNotes $notes
+./New-Release.ps1 -ReleaseNotes $notes
 ```
 
 ## 🗒️ Changelog