getculpa 0.0.1 → 1.0.1

package/assets/launch-culpa.ps1

@@ -0,0 +1,350 @@
+# Culpa launcher (Culpaflight #2, 2026-07-27). The Desktop/Start-Menu shortcut
+# runs THIS instead of a bare URL: a bare .url dead-ends at "connection
+# refused" whenever Docker Desktop isn't running. This launcher makes launch
+# mean launch: ensure Docker is up (starting it if installed, asking if not),
+# ensure the Culpa stack is up, then open the dashboard. Bounded waits, loud
+# failures - same posture as the installer.
+
+$ErrorActionPreference = "Stop"
+# IWR's progress rendering throws in hidden/redirected consoles (PS 5.1) and
+# slows every request - silence it globally
+$ProgressPreference = "SilentlyContinue"
+
+# CF5-F11: the shortcut runs this from the install directory, wherever the
+# founder put it; LOCALAPPDATA stays the fallback for the zip layout.
+$AppDir = if (Test-Path (Join-Path $PSScriptRoot "docker-compose.yml")) {
+    $PSScriptRoot
+} else {
+    Join-Path $env:LOCALAPPDATA "Culpa"
+}
+$ComposeDst = Join-Path $AppDir "docker-compose.yml"
+$DashboardUrl = "http://localhost:3000"
+# probe by literal IPv4 - "localhost" can resolve to ::1 where nothing listens
+$ProbeUrl = "http://127.0.0.1:3000"
+
+function Write-Step([string]$msg) { Write-Host "==> $msg" }
+
+function Fail([string]$msg) {
+    Write-Host ""
+    Write-Host "CULPA COULD NOT START: $msg" -ForegroundColor Red
+    Read-Host "Press Enter to close"
+    exit 1
+}
+
+function Test-DockerUp {
+    try { $null = docker info --format "ok" 2>&1; return $LASTEXITCODE -eq 0 } catch { return $false }
+}
+
+# --- QW-1..QW-4 (D-073 aftermath): the container-upgrade guards the v0.8.1
+# --- upgrade had to do by hand. Each is a plain function with injectable
+# --- inputs so scripts/cf8-qw-verify-launch-guards.ps1 can execute every
+# --- branch without Docker or a real install (the repo's AST-probe pattern).
+
+# The server tag pinned in a compose text; $null when absent (QW-1/2/3 all
+# read the pin through this ONE function so they can never disagree).
+function Get-PinnedServerVersion([string]$ComposeText) {
+    if ($ComposeText -match 'culpa-server:([^"\s]+)') { return $Matches[1] }
+    return $null
+}
+
+# vX.Y.Z comparison: -1 (A older), 0 (equal/unparsable), 1 (A newer).
+# Unparsable tags return 0 deliberately - the guards must fail OPEN on exotic
+# tags (a dev tag must not brick launch), and QW-4 still backs up on ANY
+# difference, so an unparsable tag still gets the backup.
+function Compare-CulpaVersions([string]$A, [string]$B) {
+    $rx = '^v?(\d+)\.(\d+)\.(\d+)'
+    if ($A -notmatch $rx) { return 0 }
+    $pa = @([int]$Matches[1], [int]$Matches[2], [int]$Matches[3])
+    if ($B -notmatch $rx) { return 0 }
+    $pb = @([int]$Matches[1], [int]$Matches[2], [int]$Matches[3])
+    for ($i = 0; $i -lt 3; $i++) {
+        if ($pa[$i] -lt $pb[$i]) { return -1 }
+        if ($pa[$i] -gt $pb[$i]) { return 1 }
+    }
+    return 0
+}
+
+# QW-1 - ONE canonical compose. The live file ($LivePath) owns the pin; the
+# shipped culpa-compose.yml beside the install ($ShippedPath) is only a
+# SOURCE: when an upgrade drops a NEWER shipped file, the live one is
+# re-pinned from it here, on launch - the step the v0.8.1 upgrade needed a
+# human for, three files at a time. An OLDER shipped file never wins.
+# Returns: "synced" | "kept" | "no-shipped" | "no-live".
+function Sync-CanonicalCompose([string]$ShippedPath, [string]$LivePath) {
+    if (-not (Test-Path $LivePath)) { return "no-live" }
+    if (-not (Test-Path $ShippedPath)) { return "no-shipped" }
+    $shipped = Get-PinnedServerVersion (Get-Content $ShippedPath -Raw)
+    $live = Get-PinnedServerVersion (Get-Content $LivePath -Raw)
+    if ($null -eq $shipped -or $null -eq $live) { return "kept" }
+    if ((Compare-CulpaVersions $shipped $live) -eq 1) {
+        Copy-Item $ShippedPath $LivePath -Force
+        return "synced"
+    }
+    return "kept"
+}
+
+# QW-3 - refuse-and-explain on a backward pin. $true = refuse. A pinned
+# server OLDER than the version that last booted healthily means its known
+# migrations disagree with the database's history - culpa-migrate would die
+# with a cryptic error AFTER the recreate. Refuse BEFORE touching anything.
+#
+# CodeRabbit PR13 #6: Compare-CulpaVersions fails OPEN (0, "equal") on any
+# unparsable tag so exotic dev tags never brick launch - but that means a
+# MALFORMED pin against a well-formed, known baseline used to read as
+# "equal" and launch anyway. That pin cannot be proven newer, so it must
+# fail CLOSED instead: refuse (the CULPA_ALLOW_DOWNGRADE escape still
+# applies). Both-unparsable and no-baseline stay permissive (dev installs).
+function Test-BackwardPin([string]$PinnedVersion, [string]$LastBootVersion) {
+    if ([string]::IsNullOrWhiteSpace($PinnedVersion)) { return $false }
+    if ([string]::IsNullOrWhiteSpace($LastBootVersion)) { return $false }
+    $rx = '^v?(\d+)\.(\d+)\.(\d+)'
+    if (($PinnedVersion -notmatch $rx) -and ($LastBootVersion -match $rx)) { return $true }
+    return ((Compare-CulpaVersions $PinnedVersion $LastBootVersion) -eq -1)
+}
+
+# QW-4 - automatic pg_dump before any launch that can migrate (pin differs
+# from the last healthy boot). Fails CLOSED: no verified dump, no launch -
+# unless the caller passed an explicit skip. $DumpExec/$CopyExec are
+# injectable for the probe script. Returns the dump path on success; throws
+# with a human-readable reason on failure.
+function Invoke-PreMigrationBackup {
+    param(
+        [string]$BackupDir,
+        [string]$Tag,
+        [scriptblock]$DumpExec = {
+            docker exec culpa-db sh -c "pg_dump -Fc -U culpa culpa > /tmp/culpa-pre-upgrade.dump" 2>&1 | Out-Null
+            return $LASTEXITCODE
+        },
+        [scriptblock]$CopyExec = {
+            param($Dest)
+            docker cp culpa-db:/tmp/culpa-pre-upgrade.dump $Dest 2>&1 | Out-Null
+            return $LASTEXITCODE
+        }
+    )
+    New-Item -ItemType Directory -Force -Path $BackupDir | Out-Null
+    $stamp = Get-Date -Format "yyyyMMdd-HHmmss"
+    $dest = Join-Path $BackupDir "pre-$Tag-$stamp.dump"
+    if ((& $DumpExec) -ne 0) { throw "pg_dump inside culpa-db failed" }
+    if ((& $CopyExec $dest) -ne 0) { throw "copying the dump out of culpa-db failed" }
+    $item = Get-Item -Path $dest -ErrorAction SilentlyContinue
+    if ($null -eq $item -or $item.Length -lt 1024) {
+        throw "the dump at '$dest' is missing or implausibly small ($(if ($item) { $item.Length } else { 0 }) bytes)"
+    }
+    return $dest
+}
+
+# QW-4's baseline resolver (CF8 review Critical-2): the recorded last
+# healthy boot wins; when NO record exists yet (first run of this guard on
+# an existing install - exactly the rollout population) the baseline is
+# derived from the culpa-server container's ACTUAL running image tag; if
+# neither source yields a version the baseline is UNKNOWN ("").
+function Resolve-BackupBaseline(
+    [string]$Recorded,
+    [scriptblock]$InspectExec = {
+        $old = $ErrorActionPreference; $ErrorActionPreference = "Continue"
+        try { docker inspect culpa-server --format "{{.Config.Image}}" 2>&1 } finally { $ErrorActionPreference = $old }
+    }
+) {
+    if (-not [string]::IsNullOrWhiteSpace($Recorded)) { return $Recorded.Trim() }
+    $image = ""
+    try { $image = ("$(& $InspectExec)").Trim() } catch { $image = "" }
+    if ($image -match ':(v[0-9][^:\s]*)$') { return $Matches[1] }
+    return ""
+}
+
+# QW-4's decision, extracted so the probe can execute the WIRED condition
+# (the review proved the old inline gate was silently false at
+# baseline="" + data present - the exact first-activation state): data
+# present + an UNKNOWN baseline means BACK UP, never skip; only a baseline
+# that is known AND equal to the pin skips the backup.
+function Test-BackupNeeded([bool]$DbExists, [string]$PinnedVersion, [string]$Baseline) {
+    if (-not $DbExists) { return $false }
+    if ([string]::IsNullOrWhiteSpace($Baseline)) { return $true }
+    if ([string]::IsNullOrWhiteSpace($PinnedVersion)) { return $true }
+    return ($PinnedVersion -ne $Baseline)
+}
+
+# QW-2 - reconcile the Add/Remove Programs DisplayVersion from the pin that
+# is ACTUALLY about to run, so Settings can never report a stale version
+# again (it read v0.8.0 while v0.8.1 ran). No-op when the key is absent.
+function Sync-RegistryDisplayVersion([string]$PinnedVersion, [string]$ArpKey) {
+    if ([string]::IsNullOrWhiteSpace($PinnedVersion)) { return "no-pin" }
+    if (-not (Test-Path $ArpKey)) { return "no-key" }
+    $current = (Get-ItemProperty -Path $ArpKey -Name "DisplayVersion" -ErrorAction SilentlyContinue).DisplayVersion
+    if ($current -eq $PinnedVersion) { return "unchanged" }
+    New-ItemProperty -Path $ArpKey -Name "DisplayVersion" -Value $PinnedVersion -PropertyType String -Force | Out-Null
+    return "updated"
+}
+
+# --- 1. Docker present? (CF6-9: scan, then authorize before any download) ---
+# Test-DockerInstalled takes an overridable -Probe so this exact detection can
+# be exercised with a fake "not found" result without touching a real install.
+function Test-DockerInstalled {
+    param([scriptblock]$Probe = { Get-Command docker -ErrorAction SilentlyContinue })
+    return ($null -ne (& $Probe))
+}
+
+# Real WPF dialog - not a console prompt. Names what's missing, what would be
+# downloaded, and from where; returns $false unless the user explicitly agrees.
+function Show-DockerAuthorizationModal {
+    Add-Type -AssemblyName PresentationFramework
+    $msg = "Culpa needs Docker Desktop and it was not found on this machine.`n`n" +
+        "If you authorize, Culpa will install it via winget (Windows Package Manager) " +
+        "using the official package 'Docker.DockerDesktop', or open the official " +
+        "download page at https://www.docker.com/products/docker-desktop/ if winget " +
+        "is unavailable.`n`nNothing is downloaded until you click Yes."
+    $btns = [System.Windows.MessageBoxButton]::YesNo
+    $icon = [System.Windows.MessageBoxImage]::Warning
+    $result = [System.Windows.MessageBox]::Show($msg, "Culpa - Docker Desktop required", $btns, $icon)
+    return ($result -eq [System.Windows.MessageBoxResult]::Yes)
+}
+
+# Only called after explicit authorization. Prefers winget (the user's own,
+# auditable package manager); falls back to opening the official vendor page.
+# Returns WHICH path it took (see install-culpa.ps1 for the full rationale):
+# "installed" | "page-opened" | "failed:<exit code>". A bare $false made the
+# caller claim a download page had been opened when winget was present and the
+# install simply failed - no page is opened on that path.
+function Install-DockerDesktop {
+    $winget = Get-Command winget -ErrorAction SilentlyContinue
+    if ($null -eq $winget) {
+        Start-Process "https://www.docker.com/products/docker-desktop/"
+        return "page-opened"
+    }
+    Write-Step "Installing Docker Desktop via winget (Docker.DockerDesktop)"
+    $wingetArgs = @("install", "--id", "Docker.DockerDesktop", "-e", "--accept-package-agreements", "--accept-source-agreements")
+    $p = Start-Process -FilePath "winget" -ArgumentList $wingetArgs -Wait -PassThru -NoNewWindow
+    if ($p.ExitCode -eq 0) { return "installed" }
+    return "failed:$($p.ExitCode)"
+}
+
+if (-not (Test-DockerInstalled)) {
+    if (-not (Show-DockerAuthorizationModal)) {
+        Fail "Docker Desktop download was not authorized. Nothing was changed."
+    }
+    $outcome = Install-DockerDesktop
+    if ($outcome -eq "page-opened") {
+        Fail "winget is not available, so Docker Desktop could not be installed automatically. The official download page has been opened - install it, start it once, then launch Culpa again."
+    }
+    if ($outcome -ne "installed") {
+        $code = $outcome -replace "^failed:", ""
+        Fail "winget could not install Docker Desktop (exit code $code). No download page was opened and nothing was changed. Install Docker Desktop from https://www.docker.com/products/docker-desktop/, start it once, then launch Culpa again."
+    }
+    Fail "Docker Desktop was installed. Close this window and open Culpa again to finish starting the stack."
+}
+
+# --- 2. Docker running? Start it if not (the whole point of this launcher) ---
+if (-not (Test-DockerUp)) {
+    Write-Step "Docker Desktop is not running - starting it"
+    $desktop = Join-Path $env:ProgramFiles "Docker\Docker\Docker Desktop.exe"
+    if (Test-Path $desktop) {
+        Start-Process $desktop
+    } else {
+        Fail "Docker Desktop is installed but its executable was not found at '$desktop'. Start Docker Desktop yourself, then launch Culpa again."
+    }
+    # bounded wait: up to 120s for the engine
+    $up = $false
+    for ($i = 0; $i -lt 60; $i++) {
+        Start-Sleep -Seconds 2
+        if (Test-DockerUp) { $up = $true; break }
+    }
+    if (-not $up) { Fail "Docker Desktop did not come up within 2 minutes. Wait for the whale icon to settle, then launch Culpa again." }
+}
+
+# --- 3. Stack up (idempotent; also recovers a stopped stack) ---
+if (-not (Test-Path $ComposeDst)) { Fail "Culpa's compose file is missing at '$ComposeDst'. Re-run the installer." }
+
+# --- 3a. QW-1: one canonical compose - a newer shipped culpa-compose.yml
+# --- re-pins the live file here, never by hand across three copies
+$ShippedCompose = Join-Path $AppDir "culpa-compose.yml"
+$syncOutcome = Sync-CanonicalCompose -ShippedPath $ShippedCompose -LivePath $ComposeDst
+if ($syncOutcome -eq "synced") { Write-Step "Upgrade detected: live compose re-pinned from the shipped culpa-compose.yml" }
+
+# --- 3b. QW-3: refuse-and-explain when the pin goes BACKWARD vs the last
+# --- healthy boot (a stale pin against a migrated DB dies cryptically in
+# --- culpa-migrate - refuse before touching anything)
+$PinnedVersion = Get-PinnedServerVersion (Get-Content $ComposeDst -Raw)
+$LastBootFile = Join-Path $AppDir "last-boot-version.txt"
+$LastBootVersion = if (Test-Path $LastBootFile) { (Get-Content $LastBootFile -Raw).Trim() } else { "" }
+if ((Test-BackwardPin $PinnedVersion $LastBootVersion) -and ($env:CULPA_ALLOW_DOWNGRADE -eq "1")) {
+    Write-Host "WARNING: CULPA_ALLOW_DOWNGRADE=1 - launching an OLDER server ($PinnedVersion) against a database last used by $LastBootVersion." -ForegroundColor Yellow
+}
+if ((Test-BackwardPin $PinnedVersion $LastBootVersion) -and ($env:CULPA_ALLOW_DOWNGRADE -ne "1")) {
+    Fail @"
+The compose file pins culpa-server $PinnedVersion, but this machine last ran $LastBootVersion.
+Starting an OLDER server against a newer database would fail inside its migration step with a
+cryptic error. Nothing was started.
+
+Fix: re-run the current installer (which lays down the right compose), or restore the
+$LastBootVersion pin in '$ComposeDst'. To force this downgrade anyway (only after restoring a
+matching database backup), set CULPA_ALLOW_DOWNGRADE=1 and launch again.
+"@
+}
+
+# --- 3c. QW-4: automatic pg_dump before any launch that can migrate. Fails
+# --- closed: no verified backup, no launch (CULPA_SKIP_BACKUP=1 overrides,
+# --- loudly). Only runs when the DB container already exists - a first
+# --- install has nothing to back up.
+$oldEapQw = $ErrorActionPreference
+$ErrorActionPreference = "Continue"
+$containerNames = docker ps -a --format "{{.Names}}" 2>&1
+$dbExists = ($LASTEXITCODE -eq 0 -and "$containerNames" -match "culpa-db")
+$ErrorActionPreference = $oldEapQw
+$BackupBaseline = Resolve-BackupBaseline $LastBootVersion
+$BaselineLabel = if ([string]::IsNullOrWhiteSpace($BackupBaseline)) { "unknown" } else { $BackupBaseline }
+if (Test-BackupNeeded $dbExists $PinnedVersion $BackupBaseline) {
+    if ($env:CULPA_SKIP_BACKUP -eq "1") {
+        Write-Host "WARNING: CULPA_SKIP_BACKUP=1 - upgrading $BaselineLabel -> $PinnedVersion WITHOUT a database backup." -ForegroundColor Yellow
+    } else {
+        Write-Step "Version change ($BaselineLabel -> $PinnedVersion): backing up the database first"
+        & { $ErrorActionPreference = "Continue"; docker compose -f $ComposeDst -p culpa up -d db 2>&1 | ForEach-Object { "$_" } }
+        if ($LASTEXITCODE -ne 0) { Fail "Could not start the database container to take the pre-upgrade backup. Nothing else was started." }
+        $pgReady = $false
+        for ($i = 0; $i -lt 30; $i++) {
+            & { $ErrorActionPreference = "Continue"; $null = docker exec culpa-db pg_isready -U culpa 2>&1 }
+            if ($LASTEXITCODE -eq 0) { $pgReady = $true; break }
+            Start-Sleep -Seconds 2
+        }
+        if (-not $pgReady) { Fail "The database did not become ready within 60s, so the pre-upgrade backup could not be taken. Nothing was upgraded." }
+        try {
+            $dump = Invoke-PreMigrationBackup -BackupDir (Join-Path $AppDir "backups") -Tag $BaselineLabel
+            Write-Step "Backup verified: $dump"
+        } catch {
+            Fail "Pre-upgrade backup failed ($($_.Exception.Message)). Nothing was upgraded. Set CULPA_SKIP_BACKUP=1 to launch without a backup (not recommended)."
+        }
+    }
+}
+
+Write-Step "Starting Culpa"
+# compose writes PROGRESS to stderr; under EAP=Stop with redirected streams
+# (PS 5.1) that becomes a terminating NativeCommandError - stringify the
+# records and judge by the exit code, which is the real signal
+& { $ErrorActionPreference = "Continue"; docker compose -f $ComposeDst -p culpa up -d 2>&1 | ForEach-Object { "$_" } }
+if ($LASTEXITCODE -ne 0) { Fail "Docker could not start the Culpa services. The message above says why." }
+
+# --- 3b. Capture collector (CF18): idempotent restart with the stack ---
+# The collector is a host process (loopback-bound by design), so the compose
+# restart policy cannot revive it after a reboot; this launcher is what does.
+$CollectorCtl = Join-Path $PSScriptRoot "culpa-collector.ps1"
+if (Test-Path $CollectorCtl) { & $CollectorCtl -Start }
+
+# --- 4. Wait for the dashboard (bounded: 120s), then open it ---
+Write-Step "Waiting for the dashboard"
+$ready = $false
+for ($i = 0; $i -lt 60; $i++) {
+    try {
+        $resp = Invoke-WebRequest -Uri $ProbeUrl -UseBasicParsing -TimeoutSec 3
+        if ($resp.StatusCode -eq 200) { $ready = $true; break }
+    } catch { Start-Sleep -Seconds 2 }
+}
+if (-not $ready) { Fail "The services started but the dashboard did not answer within 2 minutes. Run 'docker logs culpa-dashboard' to see why." }
+
+# --- 5. Healthy boot: record it (QW-3's baseline) + reconcile the registry
+# --- version from the pin that actually runs (QW-2)
+if ($PinnedVersion) {
+    Set-Content -Path $LastBootFile -Value $PinnedVersion
+    $ArpKey = "HKCU:\Software\Microsoft\Windows\CurrentVersion\Uninstall\{B7A6F2C4-9D31-4E5A-A0C8-52C1E7D94F60}_is1"
+    $null = Sync-RegistryDisplayVersion -PinnedVersion $PinnedVersion -ArpKey $ArpKey
+}
+
+Start-Process $DashboardUrl