diff --git a/CHANGELOG.md b/CHANGELOG.md index e0a3ec5..ceba927 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,6 +2,16 @@ Wersje zgodne z [Keep a Changelog](https://keepachangelog.com/pl/1.1.0/) i [SemVer](https://semver.org/lang/pl/). +## [1.1.0] - 2026-11-20 + +### Dodano +- Opcjonalny format `--json` dla `list`, `status` i `check` z jednoznacznymi polami i kodami wyjścia. +- Testy JSON: brak projektów, stan serwera, HTTP 200/404 oraz błędne argumenty. +- Instrukcje integracji CLI z agentami Cursor, Codex i Claude Code w README. + +### Zgodność +- Tekstowe odpowiedzi poleceń bez `--json` pozostają bez zmian. + ## [1.0.0] - 2026-11-20 ### Dodano diff --git a/README.md b/README.md index 9de044d..6621549 100644 --- a/README.md +++ b/README.md @@ -103,9 +103,9 @@ devserver add sample-bot --path "/c/projects/test" --no-dir --yes | `devserver start NAZWA` | Uruchamia serwer | | `devserver stop NAZWA` | Zatrzymuje zarządzany serwer | | `devserver restart NAZWA` | Zatrzymuje i ponownie uruchamia | -| `devserver list` | Wyświetla projekty, porty, katalogi WWW, stan i uptime procesów PHP | +| `devserver list [--json]` | Wyświetla projekty, porty, katalogi WWW, stan i uptime procesów PHP; opcjonalnie JSON | | `devserver status` | Alias `list`, zachowany dla zgodności ze starszymi wywołaniami | -| `devserver check NAZWA [--path /up]` | Sprawdza HTTP metodą GET (5 s, bez przekierowań) | +| `devserver check NAZWA [--path /up] [--json]` | Sprawdza HTTP metodą GET (5 s, bez przekierowań); opcjonalnie JSON | | `devserver logs NAZWA [--lines N] [--stdout] [--follow]` | Odczytuje log PHP (domyślnie ostatnie 30 linii stderr) | | `devserver edit NAZWA [OPCJE]` | Zmienia ścieżkę projektu, katalog WWW i port (serwer musi być zatrzymany) | | `devserver start-all` | Uruchamia wszystkie | @@ -174,6 +174,79 @@ Numer wersji przechowywany jest w pliku `VERSION` i wyświetlany przez `devserve Wydania oznaczamy tagami Git `vX.Y.Z` i publikujemy w GitHub Releases. Numer w `VERSION` identyfikuje kod, a tagi i wydania są publikowane osobno. +## Integracja z agentami AI (Cursor, Codex, Claude Code) + +Menedżer działa przez CLI, więc agent AI, który ma dostęp do terminala na Windows, może nim zarządzać bez dodatkowego serwera MCP. Agent musi mieć dostęp do `devserver` w `PATH` (Git Bash) lub uruchamiać skrypt `devserver.ps1` przez PowerShell. Polecenia wykonują się **lokalnie na komputerze**, a nie w odizolowanym środowisku zdalnym. Uprawnienia do wykonywania poleceń zależą od konfiguracji agenta. + +### Odczyt maszynowy: `--json` + +```bash +devserver list --json +devserver status --json +devserver check example-app --path /up --json +``` + +Przykład odpowiedzi `list --json` (dane przykładowe): + +```json +{ + "version": "1.1.0", + "projects": [ + { + "name": "example-app", + "status": "RUNNING", + "running": true, + "pid": 12345, + "port": 3000, + "url": "http://127.0.0.1:3000", + "path": "C:\\projects\\example-app", + "document_root": "public", + "uptime_seconds": 123 + } + ] +} +``` + +Przy braku projektów `projects` jest pustą tablicą `[]`. `document_root`, `pid` i `uptime_seconds` mogą mieć wartość `null`; port i czas działania są liczbami. `status` ma wartości `RUNNING` albo `STOPPED`. Uwaga: pole `path` zawiera **lokalną ścieżkę**, dlatego nie publikuj surowych wyników zawierających prywatne lokalizacje projektów. + +Przykład odpowiedzi `check --json`: + +```json +{ + "name": "example-app", + "url": "http://127.0.0.1:3000/up", + "http_status": 200, + "response_time_ms": 14, + "ok": true +} +``` + +Pole `ok` oznacza, że serwer odpowiedział kodem HTTP poniżej 500. Odpowiedzi 4xx nadal mają `ok: true` (serwer odpowiada, ale żądany zasób może być niedostępny). Przy kodzie 5xx narzędzie wypisuje JSON z `ok: false` i kończy działanie z kodem 1. Błędy argumentów, brak uruchomionego serwera lub problemy połączenia zwracają obiekt `{"error":{"message":"..."}}` i kod wyjścia 1. W innych trybach zachowany jest dotychczasowy format tekstowy. + +### Instrukcje dla agenta + +Wklej poniższe wskazówki do instrukcji wybranego agenta. Każdy agent korzysta z tych samych komend CLI: + +```text +Do obsługi lokalnych aplikacji PHP korzystaj z PHP DevServer Manager. +Najpierw uruchom devserver list --json; nie uruchamiaj ponownie serwera, który działa. +Dla zarejestrowanego bieżącego projektu używaj devserver start . i devserver check . --json. +Przy błędach analizuj devserver logs . --lines 50. +Nie rejestruj nowych projektów, nie zatrzymuj innych serwerów i nie używaj stop-all bez zgody. +Nie używaj --no-dir bez upewnienia się, że katalog nie zawiera plików poufnych. +Nie traktuj HTTP 200 jako potwierdzenia poprawności funkcjonalnej aplikacji. +Nie publikuj logów ani wyników list --json bez usunięcia prywatnych ścieżek. +Jeśli devserver nie jest dostępny, zgłoś problem zamiast samodzielnie zmieniać konfigurację. +``` + +**Cursor:** umieść instrukcje w regule projektu `.cursor/rules/php-devserver.mdc` (z nagłówkiem `---\ndescription: Local PHP development servers\nalwaysApply: true\n---` i treścią instrukcji) lub w odpowiedniej regule użytkownika. Zobacz [Cursor Rules](https://docs.cursor.com/context/rules). + +**Codex:** dopisz instrukcje do `AGENTS.md` w katalogu głównym projektu. Zobacz [Codex: AGENTS.md](https://developers.openai.com/codex/guides/agents-md). + +**Claude Code:** dopisz instrukcje do `CLAUDE.md` w katalogu głównym projektu. Zobacz [Claude Code: memory](https://code.claude.com/docs/en/memory). + +Pliki reguł dodaje się do **projektu obsługiwanego przez agenta**, nie do katalogu menedżera. Sposób udostępniania terminala i uprawnień zależy od konkretnej instalacji edytora i agenta. + ## Dane i kopie zapasowe ```text diff --git a/VERSION b/VERSION index 3eefcb9..9084fa2 100644 --- a/VERSION +++ b/VERSION @@ -1 +1 @@ -1.0.0 +1.1.0 diff --git a/devserver.ps1 b/devserver.ps1 index 74fa842..55cf377 100644 --- a/devserver.ps1 +++ b/devserver.ps1 @@ -1,5 +1,6 @@ #Requires -Version 5.1 $ErrorActionPreference = 'Stop' +$script:JsonMode = $false $base = Split-Path -Parent $MyInvocation.MyCommand.Path $script:Version = (Get-Content -LiteralPath (Join-Path $base 'VERSION') -Raw -Encoding UTF8).Trim() $config = Join-Path $base 'config\projects.json' @@ -153,7 +154,7 @@ function ValidatePort($port,$map,$exclude) { } if (!(FreePort $port)) { Fail "Port $port jest juz zajety." } } -function CheckServer($name,$map,$relative) { +function CheckServer($name,$map,$relative,$asJson) { $p = $map[$name] $proc = Managed $name $p if (!$proc) { Fail "Serwer $name nie jest uruchomiony przez menedzer." } @@ -179,7 +180,17 @@ function CheckServer($name,$map,$relative) { } $code = [int]([Net.HttpWebResponse]$response).StatusCode $watch.Stop() - Write-Host "$name | HTTP $code | $($watch.ElapsedMilliseconds) ms | $uri" + if ($asJson) { + Write-Output (ConvertTo-Json -InputObject ([ordered]@{ + name = $name + url = [string]$uri + http_status = $code + response_time_ms = [int64]$watch.ElapsedMilliseconds + ok = ($code -lt 500) + }) -Compress) + } else { + Write-Host "$name | HTTP $code | $($watch.ElapsedMilliseconds) ms | $uri" + } if ($code -ge 500) { exit 1 } } finally { if ($response) { $response.Close() } } } @@ -256,7 +267,33 @@ function EditServer($name,$map,$options) { Save $map Write-Host "Zaktualizowano $name | http://127.0.0.1:$port | $path | WWW: $(if ($null -eq $root) {'bez -t'} else {$root})" } -function ShowList($map) { +function ShowList($map,$asJson) { + if ($asJson) { + $projects = @( + foreach ($n in @($map.Keys | Sort-Object)) { + $p = $map[$n] + $proc = Managed $n $p + [ordered]@{ + name = $n + status = $(if ($proc) { 'RUNNING' } else { 'STOPPED' }) + running = [bool]$proc + pid = $(if ($proc) { [int]$proc.ProcessId } else { $null }) + port = [int]$p.port + url = "http://127.0.0.1:$($p.port)" + path = (FullPath $p) + document_root = $(if ($null -eq $p.documentRoot) { $null } else { [string]$p.documentRoot }) + uptime_seconds = $(if ($proc -and $proc.CreationDate) { + try { [math]::Max(0,[int64][math]::Floor(((Get-Date) - ([datetime]$proc.CreationDate)).TotalSeconds)) } catch { $null } + } else { $null }) + } + } + ) + Write-Output (ConvertTo-Json -InputObject ([ordered]@{ + version = $script:Version + projects = $projects + }) -Depth 6 -Compress) + return + } if ($map.Count -eq 0) { Write-Host 'Brak zarejestrowanych projektow.'; return } foreach ($n in @($map.Keys | Sort-Object)) { $p = $map[$n] @@ -275,8 +312,10 @@ function Help($topic) { Write-Host 'devserver edit [--path ] [--dir | --no-dir] [--port ] [--yes]' Write-Host 'Serwer musi byc zatrzymany. Bez --yes pytania o pozostale wartosci.' } elseif ($topic -eq 'check') { - Write-Host 'devserver check [--path /up]' - Write-Host 'GET z limitem 5s bez przekierowan; dowolny kod HTTP oznacza, ze serwer odpowiada (5xx = exit 1).' + Write-Host 'devserver check [--path /up] [--json]' + Write-Host 'GET z limitem 5s bez przekierowan; dowolny kod HTTP oznacza, ze serwer odpowiada (5xx = exit 1). --json = dane maszynowe.' + } elseif ($topic -eq 'list' -or $topic -eq 'status') { + Write-Host 'devserver list [--json] (status to alias list)' } elseif ($topic -eq 'logs') { Write-Host 'devserver logs [--lines 30] [--stdout] [--follow]' Write-Host 'Domyslnie stderr. --follow konczy sie Ctrl+C.' @@ -290,8 +329,8 @@ function Help($topic) { devserver start devserver stop devserver restart - devserver list (projekty, stan procesow i uptime) - devserver check [--path /up] + devserver list [--json] (projekty, stan procesow i uptime) + devserver check [--path /up] [--json] devserver logs [--lines 30] [--stdout] [--follow] devserver edit [--path ] [--dir | --no-dir] [--port ] [--yes] devserver start-all @@ -392,17 +431,36 @@ try { } $map = Load switch ($cmd) { - 'list' { ShowList $map } - 'status' { ShowList $map } # zgodnosc wsteczna + { $_ -in @('list','status') } { + if ($tokens.Count -gt 2 -or ($tokens.Count -eq 2 -and $tokens[1] -ne '--json')) { + Fail 'Uzycie: devserver list [--json]' + } + $script:JsonMode = ($tokens.Count -eq 2) + ShowList $map $script:JsonMode + } 'check' { - if ($tokens.Count -notin @(2,4)) { Fail 'Uzycie: devserver check [--path /up]' } - $n = ResolveName $tokens[1] $map + $script:JsonMode = ($tokens -contains '--json') + if ($tokens.Count -lt 2 -or $tokens[1].StartsWith('--')) { Fail 'Uzycie: devserver check [--path /up] [--json]' } $uriPath = '/' - if ($tokens.Count -eq 4) { - if ($tokens[2] -ne '--path') { Fail "Nieznana opcja: $($tokens[2])" } - $uriPath = $tokens[3] + $hasPath = $false + $seenJson = $false + for ($i = 2; $i -lt $tokens.Count; $i++) { + switch ($tokens[$i]) { + '--json' { + if ($seenJson) { Fail 'Powtorzona opcja: --json' } + $seenJson = $true + } + '--path' { + if ($hasPath -or $i + 1 -ge $tokens.Count -or $tokens[$i+1].StartsWith('--')) { Fail 'Brak lub powtorzenie wartosci --path.' } + $i++ + $uriPath = $tokens[$i] + $hasPath = $true + } + default { Fail "Nieznana opcja: $($tokens[$i])" } + } } - CheckServer $n $map $uriPath + $n = ResolveName $tokens[1] $map + CheckServer $n $map $uriPath $script:JsonMode } 'logs' { if ($tokens.Count -lt 2) { Fail 'Uzycie: devserver logs [--lines 30] [--stdout] [--follow]' } @@ -435,6 +493,10 @@ try { default { Fail "Nieznane polecenie '$cmd'. Uruchom: devserver help" } } } catch { - [Console]::Error.WriteLine('BLAD: ' + $_.Exception.Message) + if ($script:JsonMode) { + Write-Output (ConvertTo-Json -InputObject ([ordered]@{ error = [ordered]@{ message = $_.Exception.Message } }) -Compress) + } else { + [Console]::Error.WriteLine('BLAD: ' + $_.Exception.Message) + } exit 1 } diff --git a/tests/smoke.ps1 b/tests/smoke.ps1 index 98a2128..fdb288c 100644 --- a/tests/smoke.ps1 +++ b/tests/smoke.ps1 @@ -78,6 +78,11 @@ try { Assert ((Run @('--version')) -match ('PHP DevServer Manager ' + [regex]::Escape((Get-Content -LiteralPath (Join-Path $manager 'VERSION') -Raw).Trim()))) 'CLI version' Assert ((Run @('help','edit')) -match 'devserver edit') 'edit help' Assert ((Run @('help','logs')) -match '--follow') 'logs help' + $emptyJson = (Run @('list','--json') | ConvertFrom-Json) + Assert ($emptyJson.version -eq '1.1.0') 'JSON version' + Assert (@($emptyJson.projects).Count -eq 0) 'empty JSON projects array' + Assert ((Run @('status','--json') | ConvertFrom-Json).version -eq '1.1.0') 'JSON status alias' + Assert ((Run @('list','--unexpected') 1) -match 'Uzycie') 'reject list unknown flags' $port = FindPort $add = Run @('add','sample','--path',$project,'--dir','public','--port',"$port",'--yes') Assert ($add -match 'Dodano sample') 'add project' @@ -85,8 +90,17 @@ try { Assert ($list -match 'STOPPED') 'initial stopped state' Assert ($list -match 'uptime: -') 'stopped uptime' Assert ($list -match [regex]::Escape($project)) 'stored path' + $stopped = (Run @('list','--json') | ConvertFrom-Json) + Assert (@($stopped.projects).Count -eq 1) 'stopped JSON projects' + Assert ($stopped.projects[0].name -eq 'sample') 'JSON project name' + Assert ($stopped.projects[0].status -eq 'STOPPED') 'JSON stopped state' + Assert ($stopped.projects[0].running -eq $false) 'JSON stopped boolean' + Assert ($null -eq $stopped.projects[0].uptime_seconds) 'JSON stopped uptime' + Assert ($stopped.projects[0].port -eq $port) 'JSON port' + Assert ($stopped.projects[0].document_root -eq 'public') 'JSON document root' Assert ((Run @('add','duplicate','--path',$project,'--port',"$port",'--yes') 1) -match 'juz') 'reject duplicate path' Assert ((Run @('check','sample') 1) -match 'nie jest uruchomiony') 'reject check for stopped server' + Assert ((Run @('check','sample','--json') 1 | ConvertFrom-Json).error.message -match 'nie jest uruchomiony') 'JSON error for stopped server' $start = Run @('start','sample') Assert ($start -match 'START sample') "start server: $start" $serverStarted = $true @@ -94,10 +108,25 @@ try { $list = Run @('list') Assert ($list -match 'RUNNING') "running status: $list" Assert ($list -match 'uptime: [0-9]') "running uptime: $list" + $running = (Run @('list','--json') | ConvertFrom-Json).projects[0] + Assert ($running.status -eq 'RUNNING') 'JSON running state' + Assert ($running.running -eq $true) 'JSON running boolean' + Assert ($running.pid -gt 0) 'JSON running PID' + Assert ($running.uptime_seconds -ge 0) 'JSON uptime seconds' $http = Run @('check','sample','--path','/') Assert ($http -match 'HTTP 200') "HTTP 200: $http" + $json200 = Run @('check','sample','--json','--path','/') | ConvertFrom-Json + Assert ($json200.http_status -eq 200) 'JSON HTTP 200' + Assert ($json200.ok -eq $true) 'JSON ok for 200' + Assert ($json200.response_time_ms -ge 0) 'JSON HTTP elapsed ms' + Assert ($json200.name -eq 'sample') 'JSON HTTP name' $http404 = Run @('check','sample','--path','/missing.php') Assert ($http404 -match 'HTTP 404') "404 accepted as HTTP response: $http404" + $json404 = Run @('check','sample','--path','/missing.php','--json') | ConvertFrom-Json + Assert ($json404.http_status -eq 404 -and $json404.ok -eq $true) 'JSON HTTP 404 is responding' + Assert ((Run @('check','sample','--json','--path','//other.example/') 1 | ConvertFrom-Json).error.message -match 'Sciezka HTTP') 'JSON rejects remote host' + Assert ((Run @('check','sample','--json','--json') 1 | ConvertFrom-Json).error.message -match 'Powtorzona') 'JSON duplicate flag validation' + Assert ((Run @('check','sample','--json','--bogus') 1 | ConvertFrom-Json).error.message -match 'Nieznana') 'JSON unknown flag validation' Assert ((Run @('check','sample','--path','//other.example/') 1) -match 'Sciezka HTTP') 'reject network path' $log = Run @('logs','sample','--lines','20') Assert ($log -match 'Log:') 'read stderr log' @@ -106,6 +135,7 @@ try { $null = Run @('stop','sample') $serverStarted = $false Assert ((Run @('list')) -match 'STOPPED') 'stopped server' + Assert ((Run @('list','--json') | ConvertFrom-Json).projects[0].running -eq $false) 'JSON stopped after stop' $newPort = FindPort while ($newPort -eq $port) { $newPort = FindPort } $edited = Run @('edit','sample','--port',"$newPort",'--dir','web','--yes') @@ -123,7 +153,7 @@ try { $serverStarted = $false $null = Run @('remove','sample') Assert ((Run @('list')) -match 'Brak zarejestrowanych') 'remove project' - Write-Host 'PASS: syntax, CLI help, add, list uptime, HTTP, logs, edit, validation, start/stop/remove' + Write-Host 'PASS: syntax, CLI help, add, list JSON, HTTP JSON, logs, edit, validation, start/stop/remove' } finally { if ($serverStarted -and (Test-Path -LiteralPath $script)) { & powershell.exe -NoProfile -ExecutionPolicy Bypass -File $script stop sample | Out-Null