@tera-system/core 0.1.0

package/tools/tera-update.ps1

@@ -0,0 +1,472 @@
+<#
+  Tera Runtime Updater.
+  The release package must contain TERA_RELEASE_MANIFEST.json and SHA256SUMS.
+  Apply is fail-closed: it requires Git, a valid lockfile (or -Initialize),
+  verified hashes, and managed paths only.
+#>
+[CmdletBinding()]
+param(
+    [Parameter(Mandatory = $true)]
+    [string]$Version,
+
+    [ValidateSet('Plan', 'Apply')]
+    [string]$Mode = 'Plan',
+
+    [string]$SourcePath,
+
+    [string]$RepositoryUrl,
+
+    [string]$RepoPath = (Get-Location).Path,
+
+    [ValidateSet('stable', 'beta')]
+    [string]$Channel = 'stable',
+
+    [switch]$Initialize,
+
+    [switch]$NoCommit
+)
+
+Set-StrictMode -Version 5
+$ErrorActionPreference = 'Stop'
+
+function Fail([string]$Message) {
+    throw $Message
+}
+
+# تنفيذ git بأمان في PS 5.1: تحذيرات stderr (LF->CRLF وغيرها) يجب ألا تُوقف التنفيذ.
+# الحكم الحقيقي للنجاح/الفشل هو $LASTEXITCODE وليس نص stderr.
+# ملاحظة: المصفوفات المتداخلة تُفلت، ونمرر -c core.autocrlf=false لتعطيل تحذيرات
+# LF->CRLF التي كانت تقطع العملية في PS 5.1 مع ملفات LF داخل مستودع الزبون.
+function Invoke-Git {
+    param(
+        [Parameter(Mandatory = $true)]
+        [object[]]$Arguments
+    )
+    $flat = @()
+    foreach ($arg in $Arguments) {
+        if ($arg -is [System.Array]) { $flat += @($arg) } else { $flat += $arg }
+    }
+    $previous = $ErrorActionPreference
+    $ErrorActionPreference = 'Continue'
+    try {
+        & git -c core.autocrlf=false @flat 2>$null
+        return $LASTEXITCODE
+    }
+    finally {
+        $ErrorActionPreference = $previous
+    }
+}
+
+function Invoke-GitCapture {
+    param(
+        [Parameter(Mandatory = $true)]
+        [object[]]$Arguments
+    )
+    $flat = @()
+    foreach ($arg in $Arguments) {
+        if ($arg -is [System.Array]) { $flat += @($arg) } else { $flat += $arg }
+    }
+    $previous = $ErrorActionPreference
+    $ErrorActionPreference = 'Continue'
+    try {
+        $output = @(& git -c core.autocrlf=false @flat 2>$null)
+        return [pscustomobject]@{ Output = $output; ExitCode = $LASTEXITCODE }
+    }
+    finally {
+        $ErrorActionPreference = $previous
+    }
+}
+
+function Normalize-RelativePath([string]$Path) {
+    $normalized = ($Path -replace '\\', '/')
+    while ($normalized.StartsWith('./')) {
+        $normalized = $normalized.Substring(2)
+    }
+    return $normalized
+}
+
+function Normalize-Version([string]$Value) {
+    $result = $Value -replace '^tera-', ''
+    return ($result -replace '^v', '')
+}
+
+function Get-RequiredProperty($Object, [string]$Name, [string]$Context) {
+    if ($null -eq $Object -or -not ($Object.PSObject.Properties.Name -contains $Name)) {
+        Fail "$Context is missing required property: $Name"
+    }
+    $value = $Object.$Name
+    if ($null -eq $value -or ([string]$value).Trim().Length -eq 0) {
+        Fail "$Context has an empty required property: $Name"
+    }
+    return $value
+}
+
+function Assert-ManagedRelativePath([string]$Path) {
+    $normalized = Normalize-RelativePath $Path
+    if ([System.IO.Path]::IsPathRooted($Path) -or $normalized -match '^[A-Za-z]:') {
+        Fail "Manifest contains an absolute path: $Path"
+    }
+    if ($normalized -match '(^|/)\.\.(/|$)') {
+        Fail "Manifest contains a traversal path: $Path"
+    }
+    $allowed = @('.opencode/', 'tera-system/', 'tera-workshop/')
+    $ok = $false
+    foreach ($root in $allowed) {
+        if ($normalized.StartsWith($root, [System.StringComparison]::OrdinalIgnoreCase)) {
+            $ok = $true
+            break
+        }
+    }
+    if (-not $ok) {
+        Fail "Manifest path is outside Tera-managed roots: $Path"
+    }
+    return $normalized
+}
+
+function Read-RequiredLock([string]$Path) {
+    if (-not (Test-Path -LiteralPath $Path)) {
+        return $null
+    }
+    try {
+        $lock = Get-Content -LiteralPath $Path -Raw | ConvertFrom-Json
+    } catch {
+        Fail "lock.json is invalid JSON: $Path"
+    }
+    foreach ($name in @('version', 'tag', 'commit', 'channel', 'files')) {
+        [void](Get-RequiredProperty $lock $name 'lock.json')
+    }
+    if ($lock.channel -notin @('stable', 'beta')) {
+        Fail "lock.json has invalid channel: $($lock.channel)"
+    }
+    if ($lock.commit -notmatch '^[0-9a-fA-F]{40}$') {
+        Fail "lock.json commit must be a full 40-character SHA."
+    }
+    if ($lock.files -is [string]) {
+        Fail "lock.json files must be an array."
+    }
+    return $lock
+}
+
+function Read-Hashes([string]$Path) {
+    if (-not (Test-Path -LiteralPath $Path)) {
+        Fail "SHA256SUMS is required: $Path"
+    }
+    $hashes = @{}
+    foreach ($line in Get-Content -LiteralPath $Path) {
+        if ($line -match '^([0-9a-fA-F]{64})\s+\*?(.+)$') {
+            $hashes[(Normalize-RelativePath $matches[2])] = $matches[1].ToLowerInvariant()
+        }
+    }
+    if ($hashes.Count -eq 0) {
+        Fail "SHA256SUMS contains no valid entries."
+    }
+    return $hashes
+}
+
+function Get-GitStatusPaths([string]$Repo) {
+    $items = @()
+    $status = Invoke-GitCapture -Arguments @('-C', $Repo, 'status', '--porcelain')
+    foreach ($line in $status.Output) {
+        if ($line.Length -ge 4) {
+            $items += [pscustomobject]@{
+                Code = $line.Substring(0, 2)
+                Path = (Normalize-RelativePath $line.Substring(3).Trim('"'))
+            }
+        }
+    }
+    return $items
+}
+
+function Test-ReparsePoint([string]$Path) {
+    if (-not (Test-Path -LiteralPath $Path)) { return $false }
+    try {
+        $item = Get-Item -LiteralPath $Path -Force -ErrorAction Stop
+        return ($item.Attributes -band [System.IO.FileAttributes]::ReparsePoint) -ne 0
+    } catch {
+        return $false
+    }
+}
+
+function Assert-NoReparsePointInPath([string]$BaseRoot, [string]$RelativePath) {
+    $current = $BaseRoot
+    $parts = ($RelativePath -replace '\\', '/').Split('/')
+    for ($i = 0; $i -lt $parts.Count; $i++) {
+        if ([string]::IsNullOrWhiteSpace($parts[$i])) { continue }
+        $current = Join-Path $current $parts[$i]
+        if (Test-ReparsePoint $current) {
+            Fail "Refusing to write through reparse point (symlink/junction): $RelativePath (at $current)"
+        }
+    }
+}
+
+$RepoPath = [System.IO.Path]::GetFullPath($RepoPath)
+if (-not (Test-Path -LiteralPath $RepoPath -PathType Container)) { Fail "RepoPath does not exist: $RepoPath" }
+
+#---------------------------------------------------------------------
+# 0. Resolve source: either a local release package or a remote fetch
+#---------------------------------------------------------------------
+$tempFetchedPath = $null
+# تنظيف مضمون للحزمة المؤقتة عند أي خطأ غير مُلتقط (فشل تحقق، manifest، lock...)
+trap {
+    if ($tempFetchedPath -and (Test-Path -LiteralPath $tempFetchedPath)) {
+        Remove-Item -LiteralPath $tempFetchedPath -Recurse -Force -ErrorAction SilentlyContinue
+    }
+    break
+}
+if (-not $SourcePath) {
+    if (-not $RepositoryUrl) {
+        Fail "Either -SourcePath or -RepositoryUrl is required."
+    }
+    $fetchTool = Join-Path (Split-Path -Parent $MyInvocation.MyCommand.Path) 'tera-fetch.ps1'
+    if (-not (Test-Path -LiteralPath $fetchTool -PathType Leaf)) { Fail "tera-fetch.ps1 not found: $fetchTool" }
+    $tempFetchedPath = Join-Path ([System.IO.Path]::GetTempPath()) ("tera-fetch-" + [guid]::NewGuid().ToString('N'))
+    & $fetchTool -RepositoryUrl $RepositoryUrl -Version $Version -Channel $Channel -OutPath $tempFetchedPath
+    if ($LASTEXITCODE -ne 0) { Fail "tera-fetch.ps1 failed for $Version from $RepositoryUrl" }
+    $SourcePath = $tempFetchedPath
+}
+$SourcePath = [System.IO.Path]::GetFullPath($SourcePath)
+if (-not (Test-Path -LiteralPath $SourcePath -PathType Container)) { Fail "SourcePath does not exist: $SourcePath" }
+
+$gitRootCheck = Invoke-GitCapture -Arguments @('-C', $RepoPath, 'rev-parse', '--show-toplevel')
+$gitRoot = ($gitRootCheck.Output -join ' ').Trim()
+if ($gitRootCheck.ExitCode -ne 0 -or [string]::IsNullOrWhiteSpace($gitRoot)) {
+    Fail "RepoPath must be a Git repository."
+}
+$gitRoot = [System.IO.Path]::GetFullPath($gitRoot)
+
+$manifestPath = Join-Path $SourcePath 'TERA_RELEASE_MANIFEST.json'
+$sumsPath = Join-Path $SourcePath 'SHA256SUMS'
+if (-not (Test-Path -LiteralPath $manifestPath)) { Fail "Release manifest is required: $manifestPath" }
+try { $manifest = Get-Content -LiteralPath $manifestPath -Raw | ConvertFrom-Json } catch { Fail "Release manifest is invalid JSON." }
+
+$requestedVersion = Normalize-Version $Version
+$manifestVersion = [string](Get-RequiredProperty $manifest 'version' 'release manifest')
+$manifestTag = [string](Get-RequiredProperty $manifest 'tag' 'release manifest')
+$manifestCommit = [string](Get-RequiredProperty $manifest 'commit' 'release manifest')
+$manifestChannel = [string](Get-RequiredProperty $manifest 'channel' 'release manifest')
+$manifestFiles = Get-RequiredProperty $manifest 'files' 'release manifest'
+
+if ($manifestVersion -ne $requestedVersion) { Fail "Manifest version $manifestVersion does not match requested version $requestedVersion." }
+if ($manifestTag -ne $Version) { Fail "Manifest tag $manifestTag does not match requested tag $Version." }
+if ($manifestChannel -ne $Channel) { Fail "Manifest channel $manifestChannel does not match requested channel $Channel." }
+if ($manifestCommit -notmatch '^[0-9a-fA-F]{40}$') { Fail 'Manifest commit must be a full 40-character SHA.' }
+
+$hashes = Read-Hashes $sumsPath
+$packageFiles = New-Object System.Collections.Generic.List[string]
+foreach ($entry in @($manifestFiles)) {
+    if ($entry -isnot [string]) { Fail 'Manifest files must contain strings only.' }
+    $relative = Assert-ManagedRelativePath $entry
+    if ($packageFiles -contains $relative) { Fail "Manifest contains duplicate file: $relative" }
+    $packageFiles.Add($relative)
+    if (-not $hashes.ContainsKey($relative)) { Fail "SHA256SUMS has no hash for: $relative" }
+    $sourceFile = Join-Path $SourcePath $relative
+    if (-not (Test-Path -LiteralPath $sourceFile -PathType Leaf)) { Fail "Manifest file is missing from package: $relative" }
+    $actualHash = (Get-FileHash -LiteralPath $sourceFile -Algorithm SHA256).Hash.ToLowerInvariant()
+    if ($actualHash -ne $hashes[$relative]) { Fail "SHA256 mismatch: $relative" }
+}
+if ($packageFiles.Count -eq 0) { Fail 'Release manifest contains no files.' }
+
+$lockPath = Join-Path $RepoPath '.tera\lock.json'
+$currentLock = Read-RequiredLock $lockPath
+if ($null -eq $currentLock -and -not $Initialize) {
+    Fail 'No lock.json found. Use -Initialize explicitly for first installation.'
+}
+
+$managedSet = @{}
+foreach ($relative in $packageFiles) { $managedSet[$relative] = $true }
+$oldFiles = @()
+if ($currentLock) {
+    foreach ($entry in @($currentLock.files)) {
+        $oldFiles += Assert-ManagedRelativePath ([string]$entry)
+        $managedSet[$oldFiles[-1]] = $true
+    }
+}
+$allManaged = @($managedSet.Keys | Sort-Object)
+
+$status = @(Get-GitStatusPaths $RepoPath)
+$conflicts = @()
+foreach ($item in $status) {
+    $itemPath = $item.Path.TrimEnd('/')
+    $isDir = $item.Path.EndsWith('/')
+    $isManaged = ($itemPath -eq '.tera/lock.json' -or $managedSet.ContainsKey($itemPath))
+    # مجلد غير متتبع بالكامل داخل جذور مُدارة = معالجة كمسار مُدار
+    if (-not $isManaged -and $isDir) {
+        foreach ($managedPath in $managedSet.Keys) {
+            if ($managedPath.StartsWith($itemPath + '/')) { $isManaged = $true; break }
+        }
+    }
+    if (-not $isManaged) { continue }
+    if ($Initialize -and $item.Code -eq '??') {
+        # مع -Initialize: السماح بملفات/مجلدات غير متتبعة فقط إذا لم تتعارض مع الحزمة
+        if ($packageFiles -contains $itemPath) { $conflicts += $itemPath; continue }
+        if ($isDir) {
+            $containsPkg = $false
+            foreach ($pkg in $packageFiles) {
+                if ($pkg.StartsWith($itemPath + '/')) { $containsPkg = $true; break }
+            }
+            if ($containsPkg) { $conflicts += $itemPath }
+        }
+        continue
+    }
+    $conflicts += $itemPath
+}
+if ($conflicts.Count -gt 0) {
+    Fail ("Local changes exist in Tera-managed paths: " + ($conflicts -join ', '))
+}
+
+$newFiles = @()
+$changedFiles = @()
+$sameFiles = @()
+foreach ($relative in $packageFiles) {
+    $sourceFile = Join-Path $SourcePath $relative
+    $targetFile = Join-Path $RepoPath $relative
+    if (-not (Test-Path -LiteralPath $targetFile -PathType Leaf)) {
+        $newFiles += $relative
+    } else {
+        $targetHash = (Get-FileHash -LiteralPath $targetFile -Algorithm SHA256).Hash.ToLowerInvariant()
+        if ($targetHash -eq $hashes[$relative]) { $sameFiles += $relative } else { $changedFiles += $relative }
+    }
+}
+$deletedFiles = @()
+foreach ($relative in $oldFiles) {
+    if ($packageFiles -notcontains $relative -and (Test-Path -LiteralPath (Join-Path $RepoPath $relative))) {
+        $deletedFiles += $relative
+    }
+}
+
+Write-Host "Tera update $Version [$Channel] ($Mode)"
+Write-Host "New=$($newFiles.Count) Changed=$($changedFiles.Count) Same=$($sameFiles.Count) Deleted=$($deletedFiles.Count)"
+if ($Mode -eq 'Plan') {
+    # تنظيف الحزمة المؤقتة قبل الخروج — لا نترك مجلدات في %TEMP%
+    if ($tempFetchedPath -and (Test-Path -LiteralPath $tempFetchedPath)) {
+        Remove-Item -LiteralPath $tempFetchedPath -Recurse -Force -ErrorAction SilentlyContinue
+    }
+    Write-Host 'PLAN complete: no files were written.'
+    return
+}
+
+$backupRoot = Join-Path $RepoPath ('.tera\backups\' + (Get-Date -Format 'yyyyMMdd-HHmmss-fff'))
+$backupCreated = $false
+$touched = New-Object System.Collections.Generic.List[string]
+try {
+    $excludePath = Join-Path $RepoPath '.git\info\exclude'
+    $excludeDir = Split-Path -Parent $excludePath
+    if (-not (Test-Path -LiteralPath $excludeDir)) { New-Item -ItemType Directory -Path $excludeDir -Force | Out-Null }
+    $excludeLines = @()
+    if (Test-Path -LiteralPath $excludePath) { $excludeLines = @(Get-Content -LiteralPath $excludePath) }
+    if ($excludeLines -notcontains '.tera/backups/') {
+        Add-Content -LiteralPath $excludePath -Value '.tera/backups/' -Encoding ASCII
+    }
+    foreach ($relative in $allManaged + @('.tera/lock.json')) {
+        $targetFile = Join-Path $RepoPath $relative
+        if (Test-Path -LiteralPath $targetFile -PathType Leaf) {
+            $backupFile = Join-Path $backupRoot $relative
+            $backupDir = Split-Path -Parent $backupFile
+            if (-not (Test-Path -LiteralPath $backupDir)) { New-Item -ItemType Directory -Path $backupDir -Force | Out-Null }
+            Copy-Item -LiteralPath $targetFile -Destination $backupFile -Force
+            $backupCreated = $true
+        }
+    }
+
+    foreach ($relative in $deletedFiles) {
+        Assert-NoReparsePointInPath $RepoPath $relative
+        Remove-Item -LiteralPath (Join-Path $RepoPath $relative) -Force
+        $touched.Add($relative)
+    }
+    foreach ($relative in $packageFiles) {
+        Assert-NoReparsePointInPath $RepoPath $relative
+        $sourceFile = Join-Path $SourcePath $relative
+        $targetFile = Join-Path $RepoPath $relative
+        $targetDir = Split-Path -Parent $targetFile
+        if (-not (Test-Path -LiteralPath $targetDir)) { New-Item -ItemType Directory -Path $targetDir -Force | Out-Null }
+        Copy-Item -LiteralPath $sourceFile -Destination $targetFile -Force
+        $touched.Add($relative)
+    }
+
+    $lockDir = Split-Path -Parent $lockPath
+    if (-not (Test-Path -LiteralPath $lockDir)) { New-Item -ItemType Directory -Path $lockDir -Force | Out-Null }
+    $lock = [ordered]@{
+        version = $requestedVersion
+        tag = $manifestTag
+        commit = $manifestCommit
+        channel = $manifestChannel
+        files = @($packageFiles)
+    }
+    $lock | ConvertTo-Json -Depth 5 | Set-Content -LiteralPath $lockPath -Encoding UTF8
+    $touched.Add('.tera/lock.json')
+
+    # ضمان توزيع .gitattributes في الزبون — بدونه يفسر git diff --cached --check
+    # كل سطر CRLF (بعد تحويل autocrlf) كـ trailing whitespace ويحطم بوابة الجودة.
+    $gitattributesPath = Join-Path $RepoPath '.gitattributes'
+    $gitattributesContent = @(
+        '# Disable automatic line ending conversion for all files',
+        '* -text',
+        '',
+        '# Treat CR at end-of-line as part of the line ending, not as trailing whitespace.',
+        '* whitespace=cr-at-eol'
+    ) -join "`n"
+    $existingAttributes = ''
+    if (Test-Path -LiteralPath $gitattributesPath) {
+        $existingAttributes = [System.IO.File]::ReadAllText($gitattributesPath)
+    }
+    if ($existingAttributes.Trim() -ne $gitattributesContent.Trim()) {
+        [System.IO.File]::WriteAllText($gitattributesPath, $gitattributesContent + "`n", (New-Object System.Text.UTF8Encoding $false))
+        Write-Host "  [ATTR] Wrote .gitattributes to client repo (cr-at-eol)."
+    }
+    $gitPaths = @($packageFiles + $deletedFiles + @('.tera/lock.json', '.gitattributes'))
+    # git add على دفعات لتجنب حد طول سطر أوامر Windows (~32K)
+    $addOk = $true
+    $batchSize = 40
+    for ($i = 0; $i -lt $gitPaths.Count; $i += $batchSize) {
+        $end = [Math]::Min($i + $batchSize, $gitPaths.Count)
+        $batch = @($gitPaths[$i..($end - 1)])
+        $batchExit = Invoke-Git -Arguments @('-C', $RepoPath, 'add', '--', $batch)
+        if ($batchExit -ne 0) { $addOk = $false; break }
+    }
+    if (-not $addOk) { Fail "git add failed (exit $batchExit)." }
+    # diff --cached --check: النتيجة على stdout؛ الحكم عبر ExitCode
+    $check = Invoke-GitCapture -Arguments @('-C', $RepoPath, 'diff', '--cached', '--check')
+    if ($check.ExitCode -ne 0) { Fail ("git diff --cached --check failed: " + ($check.Output -join ' ')) }
+
+    if (-not $NoCommit) {
+        $headBefore = (Invoke-GitCapture -Arguments @('-C', $RepoPath, 'rev-parse', 'HEAD')).Output
+        $commitExit = Invoke-Git -Arguments @('-C', $RepoPath, 'commit', '-m', "TERA: update to $Version ($Channel)")
+        $headAfter = (Invoke-GitCapture -Arguments @('-C', $RepoPath, 'rev-parse', 'HEAD')).Output
+        # git commit قد يكتب قائمة الملفات الضخمة على stderr فتُقطع العملية قبل ضبط
+        # $LASTEXITCODE؛ الحكم الموثوق هو: هل تغيّر HEAD بعد الالتزام؟
+        $committed = ($headBefore -join '') -ne ($headAfter -join '')
+        if (-not $committed -and $commitExit -ne 0) {
+            Fail "git commit failed (exit $commitExit); changes remain staged for manual recovery."
+        }
+        if (-not $committed) {
+            Fail 'git commit did not change HEAD; changes remain staged for manual recovery.'
+        }
+    }
+    Write-Host "Apply complete. Backup: $backupRoot"
+}
+catch {
+    Write-Warning "Apply failed: $($_.Exception.Message)"
+    Write-Warning 'Restoring files from backup.'
+    foreach ($relative in $touched) {
+        $targetFile = Join-Path $RepoPath $relative
+        $backupFile = Join-Path $backupRoot $relative
+        if (Test-Path -LiteralPath $backupFile -PathType Leaf) {
+            Copy-Item -LiteralPath $backupFile -Destination $targetFile -Force
+        } elseif (Test-Path -LiteralPath $targetFile -PathType Leaf) {
+            Remove-Item -LiteralPath $targetFile -Force
+        }
+    }
+    [void](Invoke-Git -Arguments @('-C', $RepoPath, 'reset', '--', $allManaged, '.tera/lock.json'))
+    # إزالة أي index.lock عالق من git add/commit الفاشل — وإلا كل محاولة لاحقة تتعثر عليه
+    $staleLock = Join-Path $RepoPath '.git\index.lock'
+    if (Test-Path -LiteralPath $staleLock) {
+        Remove-Item -LiteralPath $staleLock -Force -ErrorAction SilentlyContinue
+        Write-Warning "Removed stale .git/index.lock left by a failed git operation."
+    }
+    throw
+}
+finally {
+    if ($tempFetchedPath -and (Test-Path -LiteralPath $tempFetchedPath)) {
+        Remove-Item -LiteralPath $tempFetchedPath -Recurse -Force -ErrorAction SilentlyContinue
+    }
+}

package/tools/tera-watch.ps1

@@ -0,0 +1,154 @@
+<#
+  Tera Watch — automatic update notifier for client repositories.
+  Checks the origin repository for newer releases than the installed lock.json,
+  writes .tera/update-status.json, and shows a native Windows toast when an
+  update is available.
+
+  Modes:
+    -Once             : check once and exit (used by the scheduled task)
+    (no -Once)        : loop forever, checking every -IntervalHours
+
+  Exit codes:
+    0  : up to date (or no prior installation)
+    2  : update available
+    1  : error
+
+  Source of truth: tera-system/TERA_DISTRIBUTION_POLICY.md (SCP-2026-08-15-013)
+#>
+[CmdletBinding()]
+param(
+    [Parameter(Mandatory = $true)]
+    [string]$RepositoryUrl,
+
+    [string]$RepoPath = (Get-Location).Path,
+
+    [int]$IntervalHours = 6,
+
+    [switch]$Once
+)
+
+Set-StrictMode -Version 5
+$ErrorActionPreference = 'Continue'
+
+function Fail([string]$Message) {
+    throw $Message
+}
+
+function Compare-TeraVersion([string]$a, [string]$b) {
+    $aParts = ($a -replace '^tera-v', '').Split('.')
+    $bParts = ($b -replace '^tera-v', '').Split('.')
+    for ($i = 0; $i -lt [Math]::Max($aParts.Count, $bParts.Count); $i++) {
+        $pa = 0; $pb = 0
+        if ($i -lt $aParts.Count) { [void][int]::TryParse($aParts[$i], [ref]$pa) }
+        if ($i -lt $bParts.Count) { [void][int]::TryParse($bParts[$i], [ref]$pb) }
+        if ($pa -gt $pb) { return 1 }
+        if ($pa -lt $pb) { return -1 }
+    }
+    return 0
+}
+
+function Get-OriginVersions([string]$Url) {
+    $lines = @(& git ls-remote --tags $Url 2>$null)
+    if ($LASTEXITCODE -ne 0) { Fail "Could not reach origin repository: $Url" }
+    $versions = New-Object System.Collections.Generic.List[string]
+    foreach ($line in $lines) {
+        if ($line -match 'refs/tags/(tera-v[0-9]+\.[0-9]+\.[0-9]+)(\^\{\})?$') {
+            $versions.Add($matches[1])
+        }
+    }
+    $sorted = @($versions | Sort-Object -Unique)
+    return , $sorted
+}
+
+function Show-TeraToast([string]$Title, [string]$Message) {
+    # Native WinRT toast — no external module required (Windows 10/11)
+    try {
+        $null = [Windows.UI.Notifications.ToastNotificationManager, Windows.UI.Notifications, ContentType = WindowsRuntime]
+        $null = [Windows.Data.Xml.Dom.XmlDocument, Windows.Data.Xml.Dom.XmlDocument, ContentType = WindowsRuntime]
+        $null = [Windows.UI.Notifications.ToastNotification, Windows.UI.Notifications, ContentType = WindowsRuntime]
+
+        $appId = 'Tera Update Notifier'
+        $xml = New-Object Windows.Data.Xml.Dom.XmlDocument
+        $xml.LoadXml("<toast><visual><binding template='ToastText02'><text id='1'>$Title</text><text id='2'>$Message</text></binding></visual></toast>")
+        $toast = New-Object Windows.UI.Notifications.ToastNotification $xml
+        [Windows.UI.Notifications.ToastNotificationManager]::CreateToastNotifier($appId).Show($toast)
+        return $true
+    } catch {
+        Write-Warning "Toast failed (non-critical): $($_.Exception.Message)"
+        return $false
+    }
+}
+
+function Invoke-CheckOnce {
+    $RepoPath = [System.IO.Path]::GetFullPath($RepoPath)
+    $versions = Get-OriginVersions $RepositoryUrl
+    if ($versions.Count -eq 0) {
+        Write-Host "No tera-vX.Y.Z tags found in origin."
+        return 1
+    }
+    $latest = $versions[-1]
+
+    $lockPath = Join-Path $RepoPath '.tera\lock.json'
+    $installed = $null
+    if (Test-Path -LiteralPath $lockPath) {
+        try {
+            $lock = Get-Content -LiteralPath $lockPath -Raw | ConvertFrom-Json
+            if ($lock.tag) { $installed = [string]$lock.tag }
+        } catch {
+            Write-Warning "lock.json unreadable at $lockPath"
+        }
+    }
+
+    $updateAvailable = $false
+    if ($installed) {
+        $updateAvailable = (Compare-TeraVersion $installed $latest) -lt 0
+    }
+
+    # Always write status file (readable by any session / OpenCode)
+    $status = [ordered]@{
+        checkedAt = (Get-Date -Format 'yyyy-MM-dd HH:mm:ss')
+        installed = $installed
+        latest    = $latest
+        updateAvailable = $updateAvailable
+    }
+    $teraDir = Join-Path $RepoPath '.tera'
+    if (-not (Test-Path -LiteralPath $teraDir)) { New-Item -ItemType Directory -Path $teraDir -Force | Out-Null }
+    $statusPath = Join-Path $teraDir 'update-status.json'
+    $status | ConvertTo-Json -Depth 3 | Set-Content -LiteralPath $statusPath -Encoding UTF8
+
+    if ($updateAvailable) {
+        Write-Host "UPDATE AVAILABLE: installed=$installed latest=$latest"
+        $null = Show-TeraToast 'Tera Update Available' "Installed: $installed  |  Latest: $latest"
+        return 2
+    }
+    if ($installed) {
+        Write-Host "Up to date: $installed (latest: $latest)"
+        return 0
+    }
+    Write-Host "No prior installation. Latest available: $latest"
+    return 0
+}
+
+# ---- main ----
+if ($Once) {
+    try {
+        exit (Invoke-CheckOnce)
+    } catch {
+        Write-Warning "Check failed: $($_.Exception.Message)"
+        exit 1
+    }
+}
+
+# Loop mode
+Write-Host "Tera Watch running. Checking every $IntervalHours hour(s). Ctrl+C to stop."
+while ($true) {
+    try {
+        $code = Invoke-CheckOnce
+        if ($code -eq 2) {
+            Write-Host "Notification sent. Next check in $IntervalHours hour(s)."
+        }
+    } catch {
+        Write-Warning "Check failed (will retry): $($_.Exception.Message)"
+    }
+    Start-Sleep -Seconds ($IntervalHours * 3600)
+}