Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
10 changes: 10 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
77 changes: 75 additions & 2 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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 |
Expand Down Expand Up @@ -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
Expand Down
2 changes: 1 addition & 1 deletion VERSION
Original file line number Diff line number Diff line change
@@ -1 +1 @@
1.0.0
1.1.0
94 changes: 78 additions & 16 deletions devserver.ps1
Original file line number Diff line number Diff line change
@@ -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'
Expand Down Expand Up @@ -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." }
Expand All @@ -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() } }
}
Expand Down Expand Up @@ -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]
Expand All @@ -275,8 +312,10 @@ function Help($topic) {
Write-Host 'devserver edit <nazwa|.> [--path <sciezka>] [--dir <katalog> | --no-dir] [--port <numer>] [--yes]'
Write-Host 'Serwer musi byc zatrzymany. Bez --yes pytania o pozostale wartosci.'
} elseif ($topic -eq 'check') {
Write-Host 'devserver check <nazwa|.> [--path /up]'
Write-Host 'GET z limitem 5s bez przekierowan; dowolny kod HTTP oznacza, ze serwer odpowiada (5xx = exit 1).'
Write-Host 'devserver check <nazwa|.> [--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 <nazwa|.> [--lines 30] [--stdout] [--follow]'
Write-Host 'Domyslnie stderr. --follow konczy sie Ctrl+C.'
Expand All @@ -290,8 +329,8 @@ function Help($topic) {
devserver start <nazwa|.>
devserver stop <nazwa|.>
devserver restart <nazwa|.>
devserver list (projekty, stan procesow i uptime)
devserver check <nazwa|.> [--path /up]
devserver list [--json] (projekty, stan procesow i uptime)
devserver check <nazwa|.> [--path /up] [--json]
devserver logs <nazwa|.> [--lines 30] [--stdout] [--follow]
devserver edit <nazwa|.> [--path <sciezka>] [--dir <katalog> | --no-dir] [--port <numer>] [--yes]
devserver start-all
Expand Down Expand Up @@ -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 <nazwa|.> [--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 <nazwa|.> [--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 <nazwa|.> [--lines 30] [--stdout] [--follow]' }
Expand Down Expand Up @@ -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
}
32 changes: 31 additions & 1 deletion tests/smoke.ps1
Original file line number Diff line number Diff line change
Expand Up @@ -78,26 +78,55 @@ 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'
$list = Run @('list')
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
Start-Sleep -Seconds 2
$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'
Expand All @@ -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')
Expand All @@ -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
Expand Down
Loading