vegard
9486480ebe
Maskinrommet og Claude deler samme CLI-verktøykasse. Maskinrommet kaller dem fra jobbkøen, Claude fra terminalen. Alt maskinrommet gjør kan Claude simulere — nyttig for debugging, testing og utvikling. Nye features bygges som CLI-verktøy fra start. Eksisterende kode brytes ut gradvis. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
100 lines
3.6 KiB
Markdown
100 lines
3.6 KiB
Markdown
# Unix-filosofi: Maskinrommet som orkestrator, verktøy som binaries
|
|
|
|
## Tese
|
|
|
|
Maskinrommet skal ikke *gjøre* arbeid — det skal *koordinere* arbeid.
|
|
Selve arbeidet gjøres av spesialiserte CLI-verktøy som maskinrommet
|
|
kaller. Claude har tilgang til de samme verktøyene og kan simulere
|
|
alt maskinrommet gjør.
|
|
|
|
## Prinsipp
|
|
|
|
1. **Én jobb, gjort godt.** Hvert verktøy gjør én ting — transkriberer,
|
|
rendrer, prosesserer lyd, genererer RSS. Ikke alt i én binær.
|
|
|
|
2. **Delt verktøykasse.** Maskinrommet og Claude bruker *samme* CLI-verktøy.
|
|
Maskinrommet kaller dem fra jobbkøen, Claude kaller dem fra terminalen.
|
|
Ingen hemmelig logikk som bare lever inne i maskinrommet.
|
|
|
|
3. **Orkestratoren er frontendens interface.** Frontend snakker med
|
|
maskinrommet via HTTP. Maskinrommet validerer, autoriserer, legger i
|
|
jobbkø, og delegerer til CLI-verktøy. Maskinrommet *eier* auth og
|
|
edges — men *delegerer* prosessering.
|
|
|
|
4. **Claude kan simulere alt.** Fordi maskinrommet gjør alt via CLI,
|
|
kan Claude kjøre de samme kommandoene manuelt. Nyttig for:
|
|
- Debugging ("hvorfor feiler transkripsjonen?")
|
|
- Testing ("hva skjer om jeg rendrer denne artikkelen?")
|
|
- Utvikling ("la meg prøve den nye FFmpeg-filteren direkte")
|
|
- Feilretting ("la meg re-kjøre RSS-genereringen for denne samlingen")
|
|
|
|
## Arkitektur
|
|
|
|
```
|
|
Frontend (SvelteKit)
|
|
│
|
|
▼ HTTP
|
|
Maskinrommet (Rust)
|
|
├── Auth + tilgangskontroll
|
|
├── Intentions (validering, edge-logikk)
|
|
├── Jobbkø (PG-basert)
|
|
│ │
|
|
│ ▼ spawn
|
|
│ CLI-verktøy (tools/)
|
|
│ ├── synops-transcribe (Whisper)
|
|
│ ├── synops-render (Tera → CAS)
|
|
│ ├── synops-audio (FFmpeg)
|
|
│ ├── synops-tts (ElevenLabs)
|
|
│ ├── synops-ai (LiteLLM)
|
|
│ ├── synops-rss (RSS-generering)
|
|
│ ├── synops-context (graf-oppslag)
|
|
│ ├── synops-search (fulltekstsøk)
|
|
│ └── ...
|
|
│
|
|
▼ direkte
|
|
PG, STDB, CAS
|
|
```
|
|
|
|
Claude har tilgang til hele `tools/`-katalogen og kan kjøre alt direkte:
|
|
```bash
|
|
# Maskinrommet gjør dette via jobbkøen:
|
|
synops-transcribe --cas-hash abc123 --model medium
|
|
|
|
# Claude kan gjøre det samme fra terminalen:
|
|
synops-transcribe --cas-hash abc123 --model medium
|
|
```
|
|
|
|
## Konvensjoner for CLI-verktøy
|
|
|
|
- **Input:** args + stdin + env-variabler (DATABASE_URL, CAS_ROOT)
|
|
- **Output:** stdout (strukturert — JSON eller markdown)
|
|
- **Feilhåndtering:** stderr for feilmeldinger, exit-kode != 0 ved feil
|
|
- **Ingen tilstandsendring uten flagg:** lesing er default, skriving krever
|
|
`--write` eller `--apply` (sikkerhetsnett for Claude)
|
|
- **Idempotent der mulig:** kan kjøres flere ganger uten sideeffekter
|
|
|
|
## Migrasjonsstrategi
|
|
|
|
Ikke en big-bang refaktor. Gradvis utbryting:
|
|
|
|
1. **Nye features** bygges som CLI-verktøy fra start (fase 19+)
|
|
2. **Eksisterende kode** brytes ut når den berøres — naturlig refaktor
|
|
3. **Maskinrommet** beholder auth, intentions, jobbkø og edge-logikk
|
|
4. **Jobbkø-handlere** endres fra inline-kode til `Command::new("synops-X")`
|
|
|
|
## Hva maskinrommet *beholder*
|
|
|
|
Kjernen som ikke bør brytes ut:
|
|
- Auth-middleware (JWT-validering, node-oppslag)
|
|
- Intentions (validering, STDB+PG-skriving, edge-logikk)
|
|
- Jobbkø (polling, retry, dead letter)
|
|
- Tilgangskontroll (node_access, recompute_access)
|
|
- Health-endepunkt
|
|
|
|
Alt annet — prosessering, rendering, generering — er kandidater for
|
|
CLI-verktøy.
|
|
|
|
## Bygger på
|
|
- `docs/retninger/maskinrommet.md` — orkestratorrollen
|
|
- `docs/infra/agent_api.md` — Claude sitt grensesnitt
|
|
- `tools/README.md` — verktøykatalogen
|