Punktero Devbox

Vývoj běží na sdíleném serveru („devboxu") a každý projekt je tam vlastní složka s vlastním devcontainerem a vlastním blokem portů. Tahle extension je k tomu rozcestník: v postranním panelu vidíš všechny instance, jestli běží, na jakém portu, a jedním klikem je otevřeš, zastavíš, natáhneš do nich data z produkce, založíš novou nebo smažeš starou.

Bez ní to samé znamená pamatovat si jména složek, porty a docker příkazy — a pro sync dat kus dokumentace navíc.

Než začneš

Extension nic neinstaluje ani nekonfiguruje za tebe. Potřebuje:

• ssh přístup na devbox — nejlépe jako alias v ~/.ssh/config, ať stačí napsat ssh devbox. Alias pak zadáš do nastavení extension.
• klíč načtený v ssh agentu (ssh-add -l něco vypíše). Bez něj extension poradí, co s tím, místo aby spadla na „Permission denied".
• právo na docker na devboxu — tedy členství ve skupině docker.
• na devboxu adresář s projekty, ve výchozím nastavení ~/projects.

Sync dat navíc potřebuje, aby z tvého notebooku byla vidět produkce. Devbox na ni nevidí, proto sync běží odsud a produkci devboxu na dobu běhu protuneluje. Ze stejného důvodu extension vždy běží na notebooku, i když máš okno připojené do devboxu.

Panel

V Activity Baru přibude ikona Devbox:

DEVBOX / INSTANCE                    ⟳  +
─────────────────────────────────────────
▾ muj-projekt          8008 · běží 4/4
    ● main       Up 2 days
    ● db         Up 2 days
    ● ws         Up 2 days
    ● scheduler  Up 2 days
▸ muj-projekt-2        8018 · zastaveno
▸ muj-projekt-3        8028 · nepostaveno
⚠ muj-projekt-4        nenakonfigurováno

Číslo je webový port instance, za ním stav jejích kontejnerů. Rozdíly, které stojí za pozornost:

• zastaveno — kontejnery existují, jen neběží. Stačí je spustit.
• nepostaveno — instance je nakonfigurovaná, ale kontejnery ještě nikdy nevznikly. Otevři ji v devcontaineru a VS Code je postaví.
• nenakonfigurováno — složka nemá .env, tedy ani blok portů. Typicky čerstvě naklonované repo; spusť na ní Nastavit porty.

Instance, ve které stojí zrovna tohle okno, je zvýrazněná a rozbalená — i když jsi v ní přes devcontainer, extension to pozná.

Co s instancí můžeš dělat

Pravý klik na instanci. Nejčastější věci mají i ikonu, která naskočí při najetí myší.

Vybrat jde i víc instancí naráz (Ctrl/Shift + klik jako v Exploreru). Hromadně fungují Otevřít, Otevřít složku a Spustit / Zastavit / Restartovat — každá instance dostane vlastní okno, respektive se akce provede na všech. Ostatní akce zůstávají na jedné instanci: platí pro tu, na kterou jsi klikl pravým tlačítkem, i když je vybráno víc. Sync ani smazání nechceš spustit na pěti instancích jedním potvrzením.

Nad tři okna se extension zeptá — každé okno postaví nebo nastartuje svůj kontejner, což chvíli trvá.

Otevřít web nejdřív ověří, že port opravdu odpovídá. Ten port totiž nepublikuje devbox — tunel staví okno VS Code připojené do instance a končí na localhostu tvého notebooku. Když instanci nemá otevřenou žádné okno, adresa by v prohlížeči jen spadla; extension proto rovnou nabídne instanci otevřít.

Sync dat z produkce

Natáhne do instance produkční databázi a obsah storage/app.

Nejdřív smaže všechny tabulky v databázi té instance. Cokoli, co sis tam rozdělal, je pryč. Proto se extension zeptá — ukáže, o kterou instanci a kterou databázi jde, a čeká na potvrzení.

Průběh uvidíš v notifikaci po krocích, celý výstup teče do panelu Output → Devbox. První sync běžně trvá desítky minut (samotný storage/app má klidně jednotky GB), další jednotky minut — přenáší se jen změny.

Dvě věci si extension ohlídá sama: srovná práva na souborech na produkci a vybere volný port pro tunel, aby si dva souběžné syncy nepřekážely.

Heslo k produkční databázi si vyžádá jednou a uloží do trezoru VS Code (SecretStorage), ne do nastavení. Sdílí se mezi všemi instancemi téhož projektu, takže se ptá opravdu jen jednou.

Nová instance

Tlačítko + v hlavičce panelu. Vybereš si, z čeho vyjít:

Data se nikdy nekopírují — nová instance je prázdná a naplní se až syncem. Díky tomu vznikne za jednotky minut, ne za hodinu.

Po založení se ještě hodí kontejner postavit: otevři instanci a nech ji VS Code sestavit.

Smazání instance

Instance po sobě nechává víc než jen složku, takže se maže všechno najednou: kontejnery, docker volume s databází, síť, images a složka. Než se cokoli stane, uvidíš soupis včetně velikosti a musíš opsat jméno instance.

Instanci otevřenou v tomhle okně nebo se běžícím syncem smazat nejde — extension to odmítne dřív, než se zeptá.

Smazání je nevratné, včetně databáze a všeho, co jsi do instance nasynchronizoval.

Nastavení

Pro sync potřebuje extension vědět, kde je produkce a jak se jmenuje databáze. Nic z toho zadávat nemusíš — čte to z Makefile té instance na devboxu, takže to zůstává v souladu s repem. Přepsat to jde profilem; vyhrává první, jehož match sedí na jméno instance:

"punkteroDevbox.syncProfiles": [
    {
        "match": "muj-projekt*",
        "server": "root@192.0.2.10",
        "serverDir": "/root/docker/muj-projekt",
        "dbName": "muj_projekt",
        "dbUser": "root"
    }
]

Když něco nefunguje

Panel hlásí, že devbox není dostupný. Zkus ssh devbox v terminálu. Když neprojde, sedí problém v ~/.ssh/config nebo v klíči, ne v extension.

ssh devbox visí a nic nevypíše. Zasekl se ControlMaster: spojení je mrtvé, ale ssh o tom neví. Ověříš to tím, že mux obejdeš — ssh -o ControlPath=none devbox 'echo ok'. Když čerstvé spojení projde, zruš master přes ssh -O exit devbox. Aby se to nestávalo, patří do ~/.ssh/config k devboxu ServerAliveInterval 20 a ServerAliveCountMax 3.

Sync spadne na přihlášení. Nejspíš nemáš klíč v agentu — ssh-add -l musí něco vypsat.

Akce v terminálu (rebuild, logy, nastavit porty) selžou v okně devcontaineru. Terminál v takovém okně běží uvnitř kontejneru, kde ssh alias devbox neexistuje. Pouštěj je z lokálního okna nebo z okna připojeného přes Remote-SSH.

Chová se to jako starší verze. Po aktualizaci extension drží VS Code v paměti tu původní, dokud okno nereloadneš: Ctrl+Shift+P → Developer: Reload Window.

Změna portů se neprojevila. Porty se do kontejneru dostávají při jeho vzniku, takže po jejich změně je potřeba Rebuild kontejneru, ne restart.

Jak to funguje uvnitř

Pár rozhodnutí, která nejsou z chování zřejmá:

• Extension běží vždy na notebooku (extensionKind: ["ui"]), i v okně připojeném do devboxu. Sync sahá na produkci i na devbox, a na produkci vidí jen notebook.
• Stav se čte jedním ssh dotazem — seznam složek, porty z jejich .env a docker ps naráz. Obnovuje se, jen když je panel viditelný.
• Skript pro sync se stahuje z té instance, kterou synchronizuješ (.devcontainer/sync-devbox.sh), takže každá jede svou verzi a nic se nerozchází s repem.
• Na docker compose extension nesáhne — zahodilo by to nadstavby, které do kontejneru přidává VS Code. Kontejnery se ovládají jednotlivě.
• Ssh spojení se nikdy neruší přes ssh -O exit; shodilo by to i připojení samotného VS Code.
• Při mazání složky může část souborů patřit rootovi — zapsaly je procesy z kontejneru. Zbytek proto uklidí kontejner běžící jako root, kterému se namountuje jen ta jedna složka.

Vývoj

npm install
npm run compile     # nebo: npm run watch
npm test            # unit testy čisté logiky (node --test)

Pak F5 → Extension Development Host. Vyžaduje, aby byla ve VS Code otevřená přímo složka vscode-devbox (kvůli .vscode/launch.json a tasku npm: compile).

Instalace do běžného VS Code:

make package
code --install-extension punktero-devbox-*.vsix --force

Po instalaci Developer: Reload Window.

Postup vydávání je v PUBLISHING.md (maintainer-only, nepublikuje se).