getculpa 0.0.1 → 1.0.2

package/LICENSE

@@ -0,0 +1,41 @@
+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
+
+To obtain the current EULA, contact the licensor at the address below.
+
+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

@@ -1,18 +1,37 @@
-# Culpa
-
-**LLM spend forensics and forecasting, local-first.**
-
-## Coming soon
-
-This package reserves the name. It prints a notice and does nothing else —
-no network calls, no files written.
-
-```bash
-npx getculpa
-```
-
-Culpa answers where your LLM spend actually went: which feature, which
-customer, which conversation — priced from a versioned price book rather than
-from provider-reported totals, with the money kept in exact decimals.
-
-More at **[getculpa.com](https://getculpa.com)**.
+# getculpa
+
+`packaging/npm-getculpa` supersedes the `installers/npm@0.0.1` name-claim
+placeholder (that package's contents are frozen; this one is the real
+package published as `getculpa` on npm).
+
+**`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.
+
+- `getculpa` / `getculpa start` — start (or resume) the Culpa stack
+- `getculpa stop` — stop the running stack (`docker compose stop`; recorded data is kept)
+- `getculpa restart` — stop, then start
+- `getculpa status` — install/docker/stack/license status (never prints key material)
+- `getculpa doctor` — diagnose this install (version/platform, file integrity, Docker, container state, ports, health, license presence — never prints key material); exits 1 if a check fails
+- `getculpa repair` — re-stage any missing/corrupt install files (never touches an existing `docker-compose.yml` or recorded data); idempotent
+- `getculpa uninstall` — remove Culpa (recorded data is kept unless you confirm)
+- `getculpa scan` — zero-install local scan, no Docker, no network
+- `getculpa connect` — print the topology-appropriate capture recipe (`--fly` also emits a ready-to-deploy Fly.io shape)
+- `getculpa update` — manage CLI launcher updates
+
+Why two layers? The npm package installs two things: the platform's `culpa`
+launcher binary (trust level: HTTPS to one hardcoded GitHub Releases origin +
+a published SHA-256 checksum — the same trust as `npm install` itself) and
+the capture collector (same trust model; its absence only turns capture off,
+nothing else degrades). Every subsequent launcher update then flows through
+a stricter path: an Ed25519-signed release manifest verified against a key
+embedded in the launcher, staged installs with a self-test, next-launch
+activation, and `culpa update rollback`.
+
+- `culpa update --check` — check for a new version (never installs)
+- `culpa update` — download, verify, stage, self-test; activates next launch
+- `culpa update --status` / `rollback`
+- `culpa config set updates.mode <auto|notify|off>` (default: notify)
+
+The package name is `getculpa` because the `culpa` npm name is not ours; the
+installed commands are `getculpa` and `culpa`.

package/assets/culpa-collector.ps1

@@ -0,0 +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

package/assets/culpa-compose.yml

@@ -0,0 +1,144 @@
+# Culpa — release compose file shipped inside the installers (T-087/T-088).
+# Net effect is identical to running the stack from the repository:
+# same services, same container names, same ports, same privacy default.
+# Images are pulled from ghcr.io; a locally built/tagged image with the same
+# name is used when present, which is how these pins were verified before
+# publication.
+#
+# ── RELEASE STATE: v1.0.2 PUBLISHED AND SIGNED (2026-08-17) ─────────
+# The line above is REWRITTEN BY installers/publish.sh at real-publish time —
+# this file has shipped a hand-edited, wrong publication claim twice, so the
+# claim is now mechanical, never prose. While it reads NOT PUBLISHED, the pins
+# below resolve only against locally built images and this file must not be
+# distributed. v0.11.0 is the CF9-CF12 round (UI alignment fixes, forecast
+# uncertainty-calibration repair + kappa bound + cohort/centring explain,
+# cache coverage flags, relay-mesh W1/W2c groundwork — feature-gated out of
+# shipped binaries) on top of v0.10.0, the CF7/CF8 round (forecast P50-anchor + cache
+# counterfactual math repair, founder UI list U-1..U-8 + P-1, founder
+# palette + card "i" tooltips, native CLI auto-update Option A, QW-1..4
+# container-upgrade guards, CodeRabbit PR#13 triage) on top of v0.9.0.
+# The relay and license-server carry NO changes since v0.9.0 and keep
+# their v0.9.0 images — a version is only claimed where a real diff
+# exists. A signed tag is never rebuilt (D-072), so new contents mean a
+# new version.
+#
+# Once the state line reads PUBLISHED AND SIGNED, verify before you run:
+#   cosign verify \
+#     --certificate-identity 'info@myaigi.ai' \
+#     --certificate-oidc-issuer 'https://github.com/login/oauth' \
+#     ghcr.io/myaigidev/culpa-server:v1.0.2
+# Repeat for culpa-dashboard. Both must report VERIFIED.
+#
+# If a pull fails with an authentication or "denied" error rather than a
+# missing manifest, the package has not been made public yet — the images
+# exist. Check with:
+#   gh api user/packages/container/culpa-server --jq .visibility
+# Do NOT use `docker manifest inspect` with an emptied DOCKER_CONFIG to test
+# this: on Docker Desktop for Windows the daemon authenticates through its own
+# credential store, so that check reports a false PUBLIC.
+
+services:
+  db:
+    image: postgres:16-alpine
+    container_name: culpa-db
+    environment:
+      POSTGRES_USER: culpa
+      POSTGRES_PASSWORD: culpa
+      POSTGRES_DB: culpa
+    volumes:
+      - culpa_pgdata:/var/lib/postgresql/data
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U culpa -d culpa"]
+      interval: 2s
+      timeout: 2s
+      retries: 30
+    restart: unless-stopped
+
+  server:
+    image: ghcr.io/myaigidev/culpa-server:v1.0.2
+    container_name: culpa-server
+    environment:
+      DATABASE_URL: postgres://culpa:culpa@db:5432/culpa
+      # full forensic capture is the default (A5); set metadata-only to opt out
+      # CF24-T1 (S2): the server binds 127.0.0.1 by DEFAULT
+      # (native/culpa-api/src/bind.rs — the binary the image actually runs).
+      # Inside a container that is unreachable through the published port, so
+      # containers must say 0.0.0.0 explicitly. The host-side `ports:` mapping
+      # below binds 127.0.0.1, so nothing OFF THIS MACHINE can reach it —
+      # reachable-by-design is always an operator's written choice, never a
+      # default.
+      #
+      # Say precisely what that does and does not cover (CF25, CodeRabbit
+      # PR #18): the `ports:` mapping governs HOST exposure only. Because the
+      # listener inside the container is 0.0.0.0, any other container attached
+      # to this Compose network reaches the server directly on 4545, without
+      # traversing the published port at all. That is ordinary Docker
+      # networking and it is fine for the services defined here — but adding a
+      # container to this network grants it API access, and the port mapping
+      # will not stop it.
+      CULPA_API_BIND: "0.0.0.0"
+      CULPA_PRIVACY_MODE: full
+      # T-120: the machine secret encrypting the customer key at rest lives
+      # here as a file — a VOLUME, so it survives container recreation
+      CULPA_SECRET_DIR: /var/lib/culpa
+      # T-M1/T-M2: scan the mounted host logs; live sweep every 5 minutes
+      CULPA_SCAN_HOME: /host
+      CULPA_SCAN_EVERY_MS: "300000"
+      # LAUNCH CONFIG (founder go, 2026-07-31 — D-041 enforcement flip;
+      # gating scope corrected 2026-08-03 by D-055): every customer-facing
+      # READ of the customer's own spend data requires a valid entitlement.
+      # Capture (ingest, scan, imports) and licensing lifecycle routes (claim,
+      # activation, license, checkout, billing-portal, entitlement, terms)
+      # are NEVER gated — a licensing failure must never break the
+      # customer's production traffic or block them from activating. Fail
+      # open ONLY on infrastructure failure (license server unreachable, DB
+      # blip, WASM missing), where the cached entitlement stands; an ABSENT
+      # or CANCELLED entitlement refuses. Activation: buy → claim in-app (or
+      # set CULPA_LICENSE_KEY, or paste the key in the dashboard under
+      # Account -> Plan & Billing -> Activate); the license server below is where the app
+      # syncs counts-only and refreshes the signed entitlement. Remove the
+      # license-server line and nothing ever leaves this machine — paid
+      # reads then stay degraded (that is the deal).
+      CULPA_TRUST_ENFORCE: "1"
+      CULPA_LICENSE_SERVER: https://culpa.fly.dev
+      # T-CF4-12 (Culpaflight4 #15): current model prices pull on first boot
+      # and refresh daily. This is a DOWNLOAD of the public price list —
+      # nothing about your usage goes anywhere (D-034). Remove the line and
+      # the committed snapshot + seeds keep pricing working offline.
+      CULPA_PRICING_SYNC: "1"
+    ports:
+      - "127.0.0.1:4545:4545"
+    volumes:
+      - culpa_data:/var/lib/culpa
+      # T-M3 ("+ See a cost"): the host's AI-tool session logs, READ-ONLY —
+      # this is what lets the in-dashboard scan see Claude Code/Codex history
+      # and keep it live. Only these two dirs, never the whole home.
+      # NARROW scope (review M2): only the session-log subdirs — ~/.claude
+      # also holds credentials/settings, which the container must never see
+      - ${CULPA_HOST_HOME:-${USERPROFILE:-${HOME:-}}}/.claude/projects:/host/.claude/projects:ro
+      - ${CULPA_HOST_HOME:-${USERPROFILE:-${HOME:-}}}/.codex/sessions:/host/.codex/sessions:ro
+    depends_on:
+      db:
+        condition: service_healthy
+    restart: unless-stopped
+
+  dashboard:
+    # CF14 (2026-08-12): dashboard-only bump. v0.11.1 is v0.11.0 plus the dark
+    # black-surface palette — no server, migration or API change, so the server
+    # above deliberately stays at v0.11.0 rather than being re-tagged for a
+    # release it has no diff in (D-072: never rebuild a tag that already exists).
+    image: ghcr.io/myaigidev/culpa-dashboard:v1.0.2
+    container_name: culpa-dashboard
+    environment:
+      CULPA_API_BASE: http://server:4545
+    ports:
+      - "127.0.0.1:3000:3000"
+    depends_on:
+      - server
+    restart: unless-stopped
+
+volumes:
+  culpa_pgdata:
+    name: culpa_pgdata
+  culpa_data:
+    name: culpa_data