# pult

Kontrollpanel för lokala utvecklingsappar. Peka på ett repo, välj branch, spara
profiler med miljövariabler — och starta/stoppa allt från en dashboard som visar
vad som körs, på vilken port och med vilken profil.

![status](https://img.shields.io/badge/status-aktiv-57cf94)

## Vad den gör

- **Appar** — registrera ett repo; projekttyp autodetekteras (Node/TypeScript
  via `package.json`, Java via `pom.xml`/Gradle, Docker via compose-fil eller
  `Dockerfile`) och git-brancher listas.
- **Standard + profiler** — utan profil körs projektets egen konfiguration
  (standardkommandot, inga env-overrides, repots nuvarande branch). Profiler är
  overrides: egen branch, eget kommando och miljövariabler — klistra in en hel
  `.env` eller redigera rad för rad. Allt sparas i SQLite.
- **Parallella körningar** — flera profiler av samma app kan köra samtidigt
  (t.ex. `PORT=3000` mot Supabase och `PORT=3001` mot lokal postgres); varje
  körning har egen rad med PID, port, uptime och stoppknapp. Samma profil kan
  också köras flera gånger, så länge varje körning får en egen port.
- **Engångsstart** — `…` bredvid Starta ger en port och miljövariabler som
  gäller just den starten. Profilen ändras inte, och värdena sparas aldrig:
  bara nyckelnamnen hamnar i körningens kvitto.
- **Pin-läge** — ⌖ i titelraden fäster pult som en smal alltid-överst-panel uppe
  till höger: en rad per app och en rad under den per körning som lever, med
  egen port och egen stoppknapp. ⌗ lossar den igen.
- **Glas** — ramlöst fönster med egen titelrad och Windows-acrylic rakt igenom.
- **Branchdisciplin** — profilens branch checkas ut före start, men bara om
  arbetsytan är ren och inga andra körningar av appen är igång. Ett smutsigt
  repo muteras aldrig.

## Kom igång

```bash
npm install
npm run dev
```

Ingen native-kompilering: databasen använder Nodes inbyggda `node:sqlite`
(Electron ≥ 35).

## Installation (Windows)

```bash
npm run dist:win
```

bygger en NSIS-installer till `release/` (per-användare, ingen admin).
App-id: `se.sockulags.pult`, produktnamn `pult`, version från `package.json`.
Kodsignering och auto-update är dokumenterade som senare steg (ingen
certifikat-/distributionskanal ännu).

## Datakataloger, backup och recovery

| Vad | Var |
| --- | --- |
| Databas (appar, profiler, miljöer, historik) | `%APPDATA%\pult\pult.db` |
| Körningsloggar | `%APPDATA%\pult\logs\run-<id>.log` |
| Hanterade worktrees | `%APPDATA%\pult\worktrees\` |

- **Backup:** kopiera `pult.db` (och `logs/` om du vill behålla loggarna).
  Stäng pult först så att skrivningar inte pågår.
- **Uppgradering** bevarar all data (samma kataloger; migreringar är
  append-only och körs automatiskt vid start).
- **Avinstallation** raderar aldrig databasen, loggarna eller worktrees —
  ta bort `%APPDATA%\pult` manuellt om du vill börja om.
- **Recovery:** kraschar pult visas körningar från förra sessionen i en banner
  vid nästa start — levande processer kan återanslutas eller stoppas; osäkra
  identiteter rörs aldrig automatiskt.

## Tray

pult lägger sig i systemfältet: visa/dölj fönstret, lista aktiva körningar,
stoppa alla (efter bekräftelse), öppna senast kraschade körning. Om
stängknappen ska avsluta eller minimera till tray väljs i tray-menyn, liksom
valfri start med Windows (avstängd som standard).

## Kommandon

| Kommando            | Gör                                        |
| ------------------- | ------------------------------------------ |
| `npm run dev`       | Startar appen med hot reload               |
| `npm test`          | Enhets-/integrationstester (vitest)        |
| `npm run typecheck` | TypeScript över main, preload och renderer |
| `npm run build`     | Produktionsbygge till `out/`               |
| `npm run e2e`       | De tolv kritiska Electron-E2E-resorna (Playwright, temporär databas) |
| `npm run dist:win`  | NSIS-installer till `release/`             |

## Språk

UI:t finns på engelska (standard) och svenska — växla med SV/EN-knappen i
verktygsraden; valet sparas lokalt. Fel- och kvittotexter från kärnan är i
nuläget svenska oavsett språkval (känd begränsning).

## Att känna till

- **Lokalt bruk.** Miljövariabler lagras i klartext i den lokala SQLite-filen —
  pult är byggd för din egen maskin, inte för delade hemligheter.
- **Worktrees.** Hanterade worktrees ligger i `%APPDATA%/pult/worktrees` och
  städas aldrig automatiskt — borttagning är alltid ett bekräftat val som
  vägrar smutsiga eller aktiva worktrees. Obs: djupa `node_modules` i en
  worktree kan nå Windows MAX_PATH-gränsen; aktivera long paths vid behov.
- **Loggretention.** Varje körning får en egen loggfil i `%APPDATA%/pult/logs`.
  Pult behåller som mest 30 loggfiler eller 200 MB totalt; äldst rensas först,
  aktiva körningars filer rörs aldrig, och rensningen raderar aldrig något
  utanför pults egen loggkatalog.
- Pult spårar bara processer den själv startat. För en översikt över *allt* som
  kör på maskinen, se systerprojektet
  [localhost-dashboard](https://github.com/sockulags/localhost-dashboard).

## MCP-server (AI-styrning)

Pult exponerar en MCP-server (Streamable HTTP) på `127.0.0.1:7858/mcp` så att
en AI-klient som Claude Code kan läsa läget, konfigurera appar och styra
körningar. Anslutningskommandot (med bearer-token) kopieras från MCP-sektionen
i appen; servern kan stängas av där. 36 verktyg i fyra grupper: läsa/förstå,
konfiguration, köra/kontrollera samt kontrollplan — plus `pult://`-resurser
(overview, appar, körningar, loggar, startgrupper, operationer).

Säkerhetsmodellen:

- **Godkännanden sker i pult.** Muterande verktyg (ta bort app, spara profil,
  applicera manifest, stoppa allt m.fl.) returnerar `awaiting_approval` och
  kör först efter ett klick i godkännandepanelen. Det finns inget
  approve-verktyg — modellen kan aldrig godkänna sin egen operation.
- **Miljövärden lämnar aldrig pult.** Profilers env maskeras (`•••`) i alla
  MCP-svar; `request_env_input` öppnar ett formulär där du fyller i värden
  direkt i pult, och modellen ser bara vilka nycklar som fylldes i.
- **Repoläsning är inhägnad.** `search_repo`/`read_repo_files` är begränsade
  till registrerade repon, blockerar `.env`, nyckel-/credentialfiler och
  `.git/`, maskar tokenmönster och har storlekstak.
- **Inga generella verktyg.** Inget shell-verktyg, ingen fri filläsning, ingen
  SQL, inga pid-kill — körkontroll går genom samma launcher-regler som UI:t
  (endast egna processer, inga branchbyten i smutsiga repon).
- **Auditlogg.** Alla anrop loggas till `logs/mcp-audit.log`; alla mutationer
  får en rad i `mcp_operation`-tabellen.

## Arkitektur

```
src/main/core/   ren kärnlogik (parseEnv, detectKind, migrate, parsePort, repoGuard) + tester
src/main/        Electron main: SQLite (node:sqlite), repo-inspektion, launcher, IPC
src/main/mcp/    MCP-server: kontrakt, registry, operations/godkännanden, tools, resurser
src/preload/     typad IPC-brygga (contextIsolation)
src/renderer/    React + TypeScript: dashboard, profiler, env-editor, loggvy
```