getculpa 1.0.10 → 1.1.0

package/LICENSE

@@ -1,43 +1,43 @@
-Culpa — proprietary software licence
-====================================
-
-Copyright (c) 2026 Myaigi AI Labs (Proprietary) Limited.
-All rights reserved.
-
-Culpa is proprietary software. It is licensed, not sold.
-
-Your use of this package, the `getculpa` and `culpa` commands it installs, the
-binaries it downloads, and the Culpa container images it runs is governed by
-the Culpa End User Licence Agreement ("EULA") between you and Myaigi AI Labs
-(Proprietary) Limited.
-
-  Licensor:      Myaigi AI Labs (Proprietary) Limited
-                 Registration number 2025/688531/07
-                 121 Senior Drive, Randburg, Gauteng, 2195, South Africa
-  Product:       Culpa
-  Governing law: Republic of South Africa
-
-The full End User Licence Agreement ships WITH the product: it is shown at
-first launch and is readable any time at /docs/terms-of-use in the app, and
-as client_docs/terms-of-use.md in the source. You do not need to ask for it.
-
-Except as the EULA expressly permits, you may not copy, modify, merge,
-publish, distribute, sublicense, sell, rent, lease, reverse engineer, or
-create derivative works of the Software, and you may not remove or alter any
-proprietary notice in it.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, TO THE FULLEST EXTENT PERMITTED BY LAW. The EULA governs warranties,
-liability, and your statutory rights, and prevails over this notice wherever
-the two differ. Nothing here limits any right you have under applicable
-consumer law that cannot lawfully be excluded.
-
-This package downloads and installs additional Culpa components at install
-time and at update time, from Culpa's official release channel, with each
-artifact verified by checksum before it is used.
-
-Third-party open-source components distributed with or downloaded by Culpa
-remain under their own licences; those licences continue to apply to them and
-nothing in this notice restricts rights granted by them.
-
-Legal notices and licensing questions: info@myaigi.ai
+Culpa — proprietary software licence
+====================================
+
+Copyright (c) 2026 Myaigi AI Labs (Proprietary) Limited.
+All rights reserved.
+
+Culpa is proprietary software. It is licensed, not sold.
+
+Your use of this package, the `getculpa` and `culpa` commands it installs, the
+binaries it downloads, and the Culpa container images it runs is governed by
+the Culpa End User Licence Agreement ("EULA") between you and Myaigi AI Labs
+(Proprietary) Limited.
+
+  Licensor:      Myaigi AI Labs (Proprietary) Limited
+                 Registration number 2025/688531/07
+                 121 Senior Drive, Randburg, Gauteng, 2195, South Africa
+  Product:       Culpa
+  Governing law: Republic of South Africa
+
+The full End User Licence Agreement ships WITH the product: it is shown at
+first launch and is readable any time at /docs/terms-of-use in the app, and
+as client_docs/terms-of-use.md in the source. You do not need to ask for it.
+
+Except as the EULA expressly permits, you may not copy, modify, merge,
+publish, distribute, sublicense, sell, rent, lease, reverse engineer, or
+create derivative works of the Software, and you may not remove or alter any
+proprietary notice in it.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, TO THE FULLEST EXTENT PERMITTED BY LAW. The EULA governs warranties,
+liability, and your statutory rights, and prevails over this notice wherever
+the two differ. Nothing here limits any right you have under applicable
+consumer law that cannot lawfully be excluded.
+
+This package downloads and installs additional Culpa components at install
+time and at update time, from Culpa's official release channel, with each
+artifact verified by checksum before it is used.
+
+Third-party open-source components distributed with or downloaded by Culpa
+remain under their own licences; those licences continue to apply to them and
+nothing in this notice restricts rights granted by them.
+
+Legal notices and licensing questions: info@myaigi.ai

package/README.md

@@ -5,11 +5,14 @@ money went, across models, features and users, on your own machine.
 
 **`npm i -g getculpa` provisions the full Culpa install — the same files,
 shortcuts, and registration the Windows installer lays down — and starts
-nothing.** `getculpa` is what wakes the stack up. On npm 12 or newer, npm
-blocks install scripts by default: install with
+nothing.** `getculpa` is what wakes the stack up. npm 12 and newer block
+install scripts by default (a Homebrew-installed npm 11.19 on macOS has been
+seen doing the same): install with
 `npm i -g --allow-scripts=getculpa getculpa` (or run
 `npm config set allow-scripts=getculpa --location=user` once). If `getculpa`
-says Culpa was never provisioned, that is why.
+says Culpa was never provisioned, that is why. On macOS the production traffic
+collector is not started automatically yet; the coding-tool scan, the gateway
+route, imports and the relay work as documented.
 
 - `getculpa` / `getculpa start` — start (or resume) the Culpa stack
 - `getculpa stop` — stop the running stack (`docker compose stop`; recorded data is kept)

package/assets/culpa-collector.ps1

@@ -1,137 +1,137 @@
-# CF18 (D-088 items 4/5) - the capture collector's lifecycle on a Windows
-# host install. ONE implementation; install-culpa.ps1, launch-culpa.ps1 and
-# uninstall-culpa.ps1 each make a one-line call, so the three can never drift.
-#
-#   culpa-collector.ps1 -Start [-MailboxUrl http://127.0.0.1:4545]
-#   culpa-collector.ps1 -Stop
-#   culpa-collector.ps1 -Status
-#
-# WHY A HOST PROCESS AND NOT A COMPOSE SERVICE: collectord binds 127.0.0.1
-# ONLY, by design (D-082 privacy boundary - raw observation material crosses
-# loopback IPC and nothing else). Docker port-publishing cannot expose a
-# loopback-bound process, so a containerized collector beside the server is
-# unreachable by an app running on the host - the common case this installer
-# serves. The native binary on the host IS the loopback the app shares.
-# (Containerized apps use deploy/capture/capture-compose.yml's netns-sharing
-# sidecar instead; `culpa connect` prints which applies.)
-#
-# The token authenticates the collector to the mailbox target. Against the
-# local culpa-api it is not currently checked (capture is never gated,
-# D-031 section 7), but collectord requires one at boot and a future hosted target
-# does check it - so a real one is generated once and persisted beside the
-# install, never a hardcoded placeholder.
-
-param(
-    [switch]$Start,
-    [switch]$Stop,
-    [switch]$Status,
-    [string]$MailboxUrl = "http://127.0.0.1:4545",
-    # CodeRabbit PR#16: overridable when 4752 is taken on the host
-    [int]$Port = 4752
-)
-
-$ErrorActionPreference = "Stop"
-$AppDir = $PSScriptRoot
-$Exe = Join-Path $AppDir "culpa-collectord-win32-x64.exe"
-$RegisterMjs = Join-Path $AppDir "register.mjs"
-$PidFile = Join-Path $AppDir "collector.pid"
-$TokenFile = Join-Path $AppDir "collector-token.txt"
-$LogFile = Join-Path $AppDir "collector.log"
-
-function Get-RunningCollectorId {
-    if (-not (Test-Path $PidFile)) { return $null }
-    $savedPid = (Get-Content $PidFile -ErrorAction SilentlyContinue | Select-Object -First 1)
-    # CodeRabbit PR#16: a corrupt PID file (partial write, manual edit) used to
-    # TERMINATE the script - Get-Process's [int] binding fails under
-    # ErrorActionPreference=Stop and SilentlyContinue does not cover binding
-    # errors. Parse defensively: garbage means "not running", never a crash.
-    $parsedPid = 0
-    if (-not [int]::TryParse("$savedPid", [ref]$parsedPid) -or $parsedPid -le 0) { return $null }
-    $proc = Get-Process -Id $parsedPid -ErrorAction SilentlyContinue
-    # PID reuse guard: only claim it is ours if the image name matches
-    if ($proc -and $proc.ProcessName -like "culpa-collectord*") { return $proc.Id }
-    return $null
-}
-
-if ($Status) {
-    $running = Get-RunningCollectorId
-    if ($running) { Write-Host "collector: running (pid $running, port $Port)" }
-    else { Write-Host "collector: not running" }
-    exit 0
-}
-
-if ($Stop) {
-    $running = Get-RunningCollectorId
-    if ($running) {
-        Stop-Process -Id $running -Force -ErrorAction SilentlyContinue
-        Write-Host "collector: stopped (pid $running)"
-    } else {
-        Write-Host "collector: was not running"
-    }
-    Remove-Item $PidFile -Force -ErrorAction SilentlyContinue
-    exit 0
-}
-
-if (-not $Start) {
-    Write-Host "usage: culpa-collector.ps1 -Start [-MailboxUrl <url>] | -Stop | -Status"
-    exit 2
-}
-
-# -- Start --------------------------------------------------------------------
-if (-not (Test-Path $Exe)) {
-    # an older zip layout without the capture plane - say so, never fail the
-    # caller's install; the stack itself is unaffected
-    Write-Host "collector: $((Split-Path $Exe -Leaf)) not present in this package - skipping capture setup" -ForegroundColor Yellow
-    exit 0
-}
-
-$existing = Get-RunningCollectorId
-if ($existing) {
-    Write-Host "collector: already running (pid $existing)"
-    exit 0
-}
-
-if (-not (Test-Path $TokenFile)) {
-    # 64 hex chars from the cryptographic RNG; persisted so restarts keep the
-    # same credential (a hosted mailbox target checks it)
-    $bytes = New-Object byte[] 32
-    [System.Security.Cryptography.RandomNumberGenerator]::Create().GetBytes($bytes)
-    ($bytes | ForEach-Object { $_.ToString("x2") }) -join "" | Set-Content $TokenFile -NoNewline
-}
-$token = Get-Content $TokenFile -Raw
-
-$env:CULPA_MAILBOX_URL = $MailboxUrl
-$env:CULPA_MAILBOX_TOKEN = $token
-$env:CULPA_COLLECTOR_PORT = "$Port"
-$proc = Start-Process -FilePath $Exe -WindowStyle Hidden -PassThru `
-    -RedirectStandardOutput $LogFile -RedirectStandardError "$LogFile.err"
-Set-Content $PidFile $proc.Id
-
-# bounded readiness wait: collectord prints "LISTENING <port>" on stdout
-$ready = $false
-for ($i = 0; $i -lt 20; $i++) {
-    Start-Sleep -Milliseconds 250
-    if ((Test-Path $LogFile) -and (Select-String -Path $LogFile -Pattern "LISTENING" -Quiet)) { $ready = $true; break }
-    if ($proc.HasExited) { break }
-}
-if (-not $ready) {
-    $detail = if (Test-Path "$LogFile.err") { Get-Content "$LogFile.err" -Raw } else { "(no log)" }
-    Write-Host "collector: failed to start - capture is OFF, everything else still works." -ForegroundColor Yellow
-    Write-Host "           $($detail.Trim())" -ForegroundColor Yellow
-    Remove-Item $PidFile -Force -ErrorAction SilentlyContinue
-    exit 0   # never fail the caller's install over capture
-}
-
-Write-Host "collector: running (pid $($proc.Id), 127.0.0.1:$Port -> $MailboxUrl)"
-Write-Host ""
-# The preload MUST be a file:// URL with forward slashes: on Windows, Node
-# parses a bare `--import=C:\...` as a URL whose scheme is `c:` and the app
-# CRASHES AT BOOT with ERR_UNSUPPORTED_ESM_URL_SCHEME. Proven live on this
-# machine during the CF18 host-path gate - this line is why the guidance
-# below is not simply $RegisterMjs.
-$RegisterUrl = "file:///" + ($RegisterMjs -replace "\\", "/")
-Write-Host "To capture a Node app on this machine, set on THAT app and restart it:" -ForegroundColor Cyan
-Write-Host "  NODE_OPTIONS=--import=$RegisterUrl"
-Write-Host "  CULPA_COLLECTOR_URL=http://127.0.0.1:$Port"
-Write-Host "(containerized app, or 2+ machines? run: culpa connect --machines <N>)"
-exit 0
+# CF18 (D-088 items 4/5) - the capture collector's lifecycle on a Windows
+# host install. ONE implementation; install-culpa.ps1, launch-culpa.ps1 and
+# uninstall-culpa.ps1 each make a one-line call, so the three can never drift.
+#
+#   culpa-collector.ps1 -Start [-MailboxUrl http://127.0.0.1:4545]
+#   culpa-collector.ps1 -Stop
+#   culpa-collector.ps1 -Status
+#
+# WHY A HOST PROCESS AND NOT A COMPOSE SERVICE: collectord binds 127.0.0.1
+# ONLY, by design (D-082 privacy boundary - raw observation material crosses
+# loopback IPC and nothing else). Docker port-publishing cannot expose a
+# loopback-bound process, so a containerized collector beside the server is
+# unreachable by an app running on the host - the common case this installer
+# serves. The native binary on the host IS the loopback the app shares.
+# (Containerized apps use deploy/capture/capture-compose.yml's netns-sharing
+# sidecar instead; `culpa connect` prints which applies.)
+#
+# The token authenticates the collector to the mailbox target. Against the
+# local culpa-api it is not currently checked (capture is never gated,
+# D-031 section 7), but collectord requires one at boot and a future hosted target
+# does check it - so a real one is generated once and persisted beside the
+# install, never a hardcoded placeholder.
+
+param(
+    [switch]$Start,
+    [switch]$Stop,
+    [switch]$Status,
+    [string]$MailboxUrl = "http://127.0.0.1:4545",
+    # CodeRabbit PR#16: overridable when 4752 is taken on the host
+    [int]$Port = 4752
+)
+
+$ErrorActionPreference = "Stop"
+$AppDir = $PSScriptRoot
+$Exe = Join-Path $AppDir "culpa-collectord-win32-x64.exe"
+$RegisterMjs = Join-Path $AppDir "register.mjs"
+$PidFile = Join-Path $AppDir "collector.pid"
+$TokenFile = Join-Path $AppDir "collector-token.txt"
+$LogFile = Join-Path $AppDir "collector.log"
+
+function Get-RunningCollectorId {
+    if (-not (Test-Path $PidFile)) { return $null }
+    $savedPid = (Get-Content $PidFile -ErrorAction SilentlyContinue | Select-Object -First 1)
+    # CodeRabbit PR#16: a corrupt PID file (partial write, manual edit) used to
+    # TERMINATE the script - Get-Process's [int] binding fails under
+    # ErrorActionPreference=Stop and SilentlyContinue does not cover binding
+    # errors. Parse defensively: garbage means "not running", never a crash.
+    $parsedPid = 0
+    if (-not [int]::TryParse("$savedPid", [ref]$parsedPid) -or $parsedPid -le 0) { return $null }
+    $proc = Get-Process -Id $parsedPid -ErrorAction SilentlyContinue
+    # PID reuse guard: only claim it is ours if the image name matches
+    if ($proc -and $proc.ProcessName -like "culpa-collectord*") { return $proc.Id }
+    return $null
+}
+
+if ($Status) {
+    $running = Get-RunningCollectorId
+    if ($running) { Write-Host "collector: running (pid $running, port $Port)" }
+    else { Write-Host "collector: not running" }
+    exit 0
+}
+
+if ($Stop) {
+    $running = Get-RunningCollectorId
+    if ($running) {
+        Stop-Process -Id $running -Force -ErrorAction SilentlyContinue
+        Write-Host "collector: stopped (pid $running)"
+    } else {
+        Write-Host "collector: was not running"
+    }
+    Remove-Item $PidFile -Force -ErrorAction SilentlyContinue
+    exit 0
+}
+
+if (-not $Start) {
+    Write-Host "usage: culpa-collector.ps1 -Start [-MailboxUrl <url>] | -Stop | -Status"
+    exit 2
+}
+
+# -- Start --------------------------------------------------------------------
+if (-not (Test-Path $Exe)) {
+    # an older zip layout without the capture plane - say so, never fail the
+    # caller's install; the stack itself is unaffected
+    Write-Host "collector: $((Split-Path $Exe -Leaf)) not present in this package - skipping capture setup" -ForegroundColor Yellow
+    exit 0
+}
+
+$existing = Get-RunningCollectorId
+if ($existing) {
+    Write-Host "collector: already running (pid $existing)"
+    exit 0
+}
+
+if (-not (Test-Path $TokenFile)) {
+    # 64 hex chars from the cryptographic RNG; persisted so restarts keep the
+    # same credential (a hosted mailbox target checks it)
+    $bytes = New-Object byte[] 32
+    [System.Security.Cryptography.RandomNumberGenerator]::Create().GetBytes($bytes)
+    ($bytes | ForEach-Object { $_.ToString("x2") }) -join "" | Set-Content $TokenFile -NoNewline
+}
+$token = Get-Content $TokenFile -Raw
+
+$env:CULPA_MAILBOX_URL = $MailboxUrl
+$env:CULPA_MAILBOX_TOKEN = $token
+$env:CULPA_COLLECTOR_PORT = "$Port"
+$proc = Start-Process -FilePath $Exe -WindowStyle Hidden -PassThru `
+    -RedirectStandardOutput $LogFile -RedirectStandardError "$LogFile.err"
+Set-Content $PidFile $proc.Id
+
+# bounded readiness wait: collectord prints "LISTENING <port>" on stdout
+$ready = $false
+for ($i = 0; $i -lt 20; $i++) {
+    Start-Sleep -Milliseconds 250
+    if ((Test-Path $LogFile) -and (Select-String -Path $LogFile -Pattern "LISTENING" -Quiet)) { $ready = $true; break }
+    if ($proc.HasExited) { break }
+}
+if (-not $ready) {
+    $detail = if (Test-Path "$LogFile.err") { Get-Content "$LogFile.err" -Raw } else { "(no log)" }
+    Write-Host "collector: failed to start - capture is OFF, everything else still works." -ForegroundColor Yellow
+    Write-Host "           $($detail.Trim())" -ForegroundColor Yellow
+    Remove-Item $PidFile -Force -ErrorAction SilentlyContinue
+    exit 0   # never fail the caller's install over capture
+}
+
+Write-Host "collector: running (pid $($proc.Id), 127.0.0.1:$Port -> $MailboxUrl)"
+Write-Host ""
+# The preload MUST be a file:// URL with forward slashes: on Windows, Node
+# parses a bare `--import=C:\...` as a URL whose scheme is `c:` and the app
+# CRASHES AT BOOT with ERR_UNSUPPORTED_ESM_URL_SCHEME. Proven live on this
+# machine during the CF18 host-path gate - this line is why the guidance
+# below is not simply $RegisterMjs.
+$RegisterUrl = "file:///" + ($RegisterMjs -replace "\\", "/")
+Write-Host "To capture a Node app on this machine, set on THAT app and restart it:" -ForegroundColor Cyan
+Write-Host "  NODE_OPTIONS=--import=$RegisterUrl"
+Write-Host "  CULPA_COLLECTOR_URL=http://127.0.0.1:$Port"
+Write-Host "(containerized app, or 2+ machines? run: culpa connect --machines <N>)"
+exit 0