Runtime závislosti — TalkIDE -- TalkIDE Internal Docs

TalkIDE internal documentation

Proč tento dokument existuje

TalkIDE platforma a generované projekty vyžadují sadu systémových nástrojů, které musí být nainstalované na hostiteli (vývojářský Mac, CI/CD runner, production container). Bez těchto nástrojů plugin skripty nebo Spring Boot aplikace selžou za běhu — typicky s nejasnou chybou daleko od skutečné příčiny.

Tento dokument je single source of truth pro seznam systémových závislostí.

Zodpovědnost za udržování: PM eviduje dokument strukturálně. Každý vývojář, který přidá novou systémovou závislost (příkaz volaný shellem, nový extern binary), musí:

přidat řádek do tabulky níže,
upravit sekci “Local development setup”,
poznamenat dopad na production image.

Tabulka závislostí

Tool	Min. verze	Použito v	Důvod	`brew install`	`apt install`	Docker base hint
yq	4.x	`plugin/scripts/_lib.sh`, `start-backend.sh`, `start-frontend.sh`	Parsování `.talkide/project.yml` (YAML). Bez něj plugin skripty okamžitě selžou s `error: yq is required`.	`brew install yq`	`apt install yq`	`RUN apt-get install -y yq` nebo `RUN wget -qO /usr/local/bin/yq ...` (viz poznámka 1)
lsof	systémová	`plugin/scripts/kill-port.sh`	Zjišťuje PID procesu poslouchajícího na daném TCP portu. Fallback na `fuser`, ale pokud ani jeden není dostupný, skript selže.	built-in macOS	`apt install lsof`	`RUN apt-get install -y lsof` (Alpine: `apk add lsof`)
curl	systémová	`plugin/scripts/start-backend.sh`, `start-frontend.sh`	Health check — čeká, dokud se proces nespustí (`curl -s -o /dev/null -w "%{http_code}"`).	built-in macOS	`apt install curl`	obvykle přítomen v base image
Java 21 (JDK/JRE)	21	talkide-be (Spring Boot), generované BE projekty (`gradlew bootRun`)	Runtime pro Spring Boot a Gradle wrapper. `build.gradle.kts` nastavuje `sourceCompatibility = JavaVersion.VERSION_21`.	`brew install openjdk@21`	`apt install openjdk-21-jdk`	`FROM eclipse-temurin:21-jre`
Gradle wrapper	8.x	generované BE projekty	`gradlew` je bundlován v každém projektu. Systémová Gradle instalace není nutná pro běh, ale může být potřeba pro initial scaffold.	`brew install gradle`	`apt install gradle`	wrapper stačí (binárku stáhne sám)
Node.js + npm	Node 22+	talkide-fe, generované FE projekty (`npm run dev`, `npm run build`)	Dev server (Vite) a build toolchain. `@tsconfig/node22` a `@types/node@^22` implikují Node 22.	`brew install node`	`apt install nodejs npm`	`FROM node:22-alpine`
Docker	24+	PostgreSQL 17 container (`docker-compose up`)	DB engine běží jako Docker container, ne nativně.	`brew install --cask docker`	viz docker.com/install	— (production má vlastní DB)
PostgreSQL 17 + pgvector	17	talkide-be DB	Databáze platformy. Image `pgvector/pgvector:pg17`.	— (přes Docker)	— (přes Docker)	`FROM pgvector/pgvector:pg17`
claude (Claude Code CLI)	latest	talkide-be `ClaudeCliService.kt`	Spouští AI agenty (`ProcessBuilder("claude", "-p", ...)`) pro generování kódu v generovaných projektech.	`npm install -g @anthropic-ai/claude-code`	`npm install -g @anthropic-ai/claude-code`	musí být v PATH production image

Poznámka 1 — yq v Docker/Alpine: Balíček yq v apt repozitářích bývá starší verze (Go implementace od mikefarah vs. Python yq). Doporučený způsob pro kontejnery:
RUN wget -qO /usr/local/bin/yq \
    https://github.com/mikefarah/yq/releases/latest/download/yq_linux_amd64 \
    && chmod +x /usr/local/bin/yq

Local development setup (macOS)

Copy-paste blok pro čistý Mac (předpokládá nainstalovaný Homebrew a npm):

brew install yq
brew install openjdk@21
brew install node
brew install --cask docker

docker pull pgvector/pgvector:pg17

npm install -g @anthropic-ai/claude-code

Ověření po instalaci:

yq --version
java -version
node --version
npm --version
docker --version
claude --version
which lsof    # built-in na macOS, mělo by najít /usr/bin/lsof
which curl    # built-in na macOS

Production / Docker requirements

TODO — finalizovat při přípravě production image. Tato sekce slouží jako přehled; konkrétní Dockerfile bude vytvořen při nasazení do produkce.

Pro každou závislost jsou níže uvedeny instalační instrukce pro Debian/Ubuntu base image. Alpine varianty jsou v tabulce výše.

# Doporučený base image pro talkide-be production
FROM eclipse-temurin:21-jre

# Systémové závislosti
RUN apt-get update && apt-get install -y \
    curl \
    lsof \
    nodejs \
    npm \
    && rm -rf /var/lib/apt/lists/*

# yq (mikefarah verze — spolehlivější než apt balíček)
RUN wget -qO /usr/local/bin/yq \
    https://github.com/mikefarah/yq/releases/latest/download/yq_linux_amd64 \
    && chmod +x /usr/local/bin/yq

# Claude Code CLI
RUN npm install -g @anthropic-ai/claude-code

Závislosti, které production image nepotřebuje přímo:

Gradle — každý generovaný projekt má vlastní gradlew, stáhne distribuci automaticky
Docker — production má vlastní DB infrastrukturu mimo container talkide-be
PostgreSQL — samostatná DB instance (viz Docker Compose v local devu)

Záměrně chybějící závislosti — headless agent tým

Mara tým agentů (plugin/agents/*.md) záměrně nepožaduje tyto nástroje:

Nástroj	Proč NENÍ závislost
JetBrains MCP (`mcp__jetbrains__*`)	Vyžaduje běžící IntelliJ/Rider IDE — nedostupné v K8s podu. Nahrazeno `Grep`/`Glob`/`Bash`.
Playwright MCP (browser MCP)	Vyžaduje Chrome + grafické prostředí — nedostupné v headless K8s podu. Pokud agent potřebuje browser pro E2E testy generované uživatelské appky, jde o separátní závislost (Stopa B).

Tato rozhodnutí jsou výsledkem Stopa 0.1 (issue talkide-be#8). Verifikace:

grep -r "jetbrains\|playwright\|ide_find\|find_references\|refactor_rename" plugin/agents/
# → prázdný výstup (žádný agent neobsahuje IDE/browser MCP tooly)

Jak přidat novou závislost

Checklist pro vývojáře:

Přidej řádek do tabulky závislostí výše (Tool, verze, použití, důvod, install příkazy)
Uprav sekci “Local development setup” — přidej brew install nebo npm install -g
Přidej instalaci do production Dockerfile sekce výše (až bude existovat reálný Dockerfile, přidej tam)
Zaznamenej do commitu zprávy, že jde o novou systémovou závislost (snazší bisect při problémech)
Ověř na čistém stroji nebo Docker containeru bez té závislosti — ujisti se, že chybová hláška je srozumitelná

Was this page helpful?

Thanks for the feedback.