From 844d4115c0791c0c7a7e03067643f59df9dc19c8 Mon Sep 17 00:00:00 2001 From: Tycjan <100317128+Tycjann@users.noreply.github.com> Date: Fri, 20 Nov 2026 15:04:40 +0100 Subject: [PATCH] docs: provide full English and Polish READMEs and English changelog --- CHANGELOG.md | 48 ++++----- README.md | 219 +++++++++++++++++++++------------------ README.pl.md | 281 +++++++++++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 423 insertions(+), 125 deletions(-) create mode 100644 README.pl.md diff --git a/CHANGELOG.md b/CHANGELOG.md index ceba927..487bc94 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,32 +1,32 @@ -# Historia zmian +# Changelog -Wersje zgodne z [Keep a Changelog](https://keepachangelog.com/pl/1.1.0/) i [SemVer](https://semver.org/lang/pl/). +This project follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and [Semantic Versioning](https://semver.org/). ## [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. +### Added +- Optional `--json` output for `list`, `status`, and `check`, with consistent fields and exit codes. +- JSON tests for empty project lists, server state, HTTP 200/404, and invalid arguments. +- README instructions for integrating Cursor, Codex, and Claude Code agents. -### Zgodność -- Tekstowe odpowiedzi poleceń bez `--json` pozostają bez zmian. +### Compatibility +- Existing text output for commands without `--json` remains unchanged. ## [1.0.0] - 2026-11-20 -### Dodano -- Zarządzanie wieloma lokalnymi serwerami PHP z Git Bash i PowerShell. -- Rejestrację i edycję projektów (`add`, `edit`, `remove`). -- Uruchamianie, zatrzymywanie i restartowanie serwerów oraz operacje zbiorcze. -- Informacje o stanie procesów i czasie działania (`list`, `status`). -- Diagnostykę HTTP (`check`) i podgląd logów (`logs`). -- Testy integracyjne uruchamiane na Windows w GitHub Actions. -- Polecenie `devserver --version` i wspólny plik `VERSION`. - -### Bezpieczeństwo -- Nasłuch ograniczony do `127.0.0.1`. -- Weryfikację tożsamości procesu przed jego zatrzymaniem. -- Ostrzeżenie o potencjalnym ujawnieniu plików przy użyciu `--no-dir`. - -### Dokumentacja -- Wstęp w języku angielskim i polskim, instrukcję konfiguracji `PATH` oraz przykłady niezwiązane z konkretnym środowiskiem. +### Added +- Management of multiple local PHP development servers using Git Bash and PowerShell. +- Project registration and editing (`add`, `edit`, `remove`). +- Starting, stopping, and restarting servers, including bulk operations. +- Process status and uptime reporting (`list`, `status`). +- HTTP diagnostics (`check`) and log viewing (`logs`). +- Windows integration tests in GitHub Actions. +- The `devserver --version` command and centralized `VERSION` file. + +### Security +- Binding limited to `127.0.0.1`. +- Process identity verification before stopping a managed server. +- Warning about possible file exposure when using `--no-dir`. + +### Documentation +- English and Polish project introductions, Git Bash `PATH` setup, and generic examples. diff --git a/README.md b/README.md index 6621549..e972d66 100644 --- a/README.md +++ b/README.md @@ -1,23 +1,23 @@ # PHP DevServer Manager -**EN:** Lightweight CLI tool for managing multiple local PHP development servers on Windows and Git Bash. Run servers independently of the terminal, monitor their status, check HTTP responses and view logs. +**English** | [Polski](README.pl.md) -**PL:** Lekkie narzędzie CLI do zarządzania wieloma lokalnymi serwerami PHP w Windows i Git Bash. Umożliwia uruchamianie serwerów niezależnie od terminala, monitorowanie ich stanu, sprawdzanie odpowiedzi HTTP oraz przeglądanie logów. +Lightweight CLI tool for managing multiple local PHP development servers on Windows and Git Bash. Run servers independently of the terminal, monitor their status, check HTTP responses, and view logs. -> **Wersja:** `1.0.0` - pierwsze stabilne wydanie menedżera CLI, przetestowane automatycznie na Windows. Wbudowany serwer PHP służy wyłącznie do developmentu i nie jest przeznaczony do obsługi ruchu produkcyjnego. +> **Version:** [Latest release](https://github.com/Tycjann/php-devserver-manager/releases/latest) (source version: [VERSION](VERSION)). The CLI has a stable release and is tested automatically on Windows. PHP's built-in web server is intended for development only, **not production traffic**. -## Wymagania +## Requirements -- Windows 10/11, PowerShell 5.1+ oraz Git Bash (Git for Windows). -- PHP CLI (`php.exe`) dostępny w **Windows PATH**, również z PowerShell. -- Uprawnienia do uruchamiania własnych procesów. Nie potrzeba uprawnień administratora. -- Polecenie `cygpath` dostępne w Git Bash. +- Windows 10/11, PowerShell 5.1+, and Git Bash (Git for Windows). +- PHP CLI (`php.exe`) available on the **Windows PATH**, including from PowerShell. +- Permission to start processes as your current user; administrator privileges are not required. +- The `cygpath` utility available in Git Bash. -## Instalacja +## Installation -Przykładowa lokalizacja to `C:\projects\devserver`. Można wybrać dowolny katalog poza katalogiem udostępnianym przez serwer HTTP. +The examples use `C:\projects\devserver`. You can choose another location, but **do not place the manager in a directory served over HTTP**. -Z Git Bash: +From Git Bash: ```bash mkdir -p /c/projects @@ -28,42 +28,42 @@ cd devserver ./devserver --version ``` -### Dostęp do polecenia z dowolnego katalogu (Git Bash) +### Run `devserver` from any directory (Git Bash) -Żeby uruchamiać `devserver` bez prefiksu `./` z każdego katalogu projektu, dodaj katalog menedżera do zmiennej `PATH` w Git Bash. W poniższych przykładach menedżer znajduje się w `C:\projects\devserver`; dostosuj ścieżkę do własnej instalacji. +To run `devserver` without the `./` prefix, add the manager directory to your Git Bash `PATH`. Adjust the example path if your installation is elsewhere. -1. Otwórz plik konfiguracyjny powłoki: +1. Open your shell configuration: ```bash nano ~/.bashrc ``` -2. Dodaj na końcu pliku: +2. Append: ```bash export PATH="/c/projects/devserver:$PATH" ``` -3. Zapisz plik, a następnie wczytaj ustawienia i sprawdź, czy polecenie jest dostępne: +3. Save the file, reload the configuration, and verify: ```bash source ~/.bashrc command -v devserver ``` - Oczekiwany wynik dla przykładowej lokalizacji: `/c/projects/devserver/devserver`. + Expected path for this example: `/c/projects/devserver/devserver`. -Od tej chwili można uruchamiać `devserver list` z dowolnego katalogu. Polecenia `devserver start .`, `devserver stop .` i `devserver restart .` korzystają z bieżącego katalogu, jeżeli jest on zarejestrowany jako projekt. +You can now run `devserver list` from any directory. Commands such as `devserver start .`, `devserver stop .`, and `devserver restart .` use the current working directory if it belongs to a registered project. -Jeżeli pojawi się `Permission denied`, nadaj uprawnienie wykonywania launcherowi (`chmod +x /c/projects/devserver/devserver`) lub wywołuj go przez `bash /c/projects/devserver/devserver ...`. +If you receive `Permission denied`, make the launcher executable with `chmod +x /c/projects/devserver/devserver`, or invoke it using `bash /c/projects/devserver/devserver ...`. -Ustawienie `~/.bashrc` dotyczy Git Bash, nie dodaje automatycznie polecenia do PowerShell ani CMD. +The `~/.bashrc` setting applies to Git Bash; it does not automatically expose the command in PowerShell or CMD. -## Pierwsze uruchomienie +## Getting started -Rejestracja może być interaktywna. Uruchom `devserver add`, aby odpowiedzieć na pytania o nazwę, lokalizację, katalog WWW i port. Naciśnięcie Enter akceptuje proponowaną wartość. Parametry podane w poleceniu nie są ponownie zadawane. `--yes` całkowicie pomija pytania, co przydaje się agentom AI. +Registration can be interactive. Run `devserver add` to be prompted for a name, project location, document root, and port. Press Enter to accept a suggested value. Options specified on the command line will not be requested again. Use `--yes` to skip all prompts, which is useful for AI agents. -Przykładowy kreator: +Example interactive session (the prompts currently appear in Polish): ```text $ devserver add @@ -73,16 +73,16 @@ Katalog WWW (- = bez -t) [public]: - Port serwera [3000]: ``` -Przejdź do katalogu aplikacji (nie do `public`): +From the application directory (not its `public` subdirectory): ```bash cd /c/projects/example-app -devserver add example-app # port automatyczny, katalog public +devserver add example-app # automatic port, public document root devserver start example-app devserver list ``` -Opcje można łączyć w dowolnej kolejności: +Options may be combined in any order: ```bash devserver add website --dir htdocs --port 3010 @@ -92,42 +92,46 @@ devserver add example-app --path "/c/projects/example-app" --port 3000 devserver add sample-bot --path "/c/projects/test" --no-dir --yes ``` -`--path` przyjmuje ścieżkę Windows (`C:\\projects\\...`) lub Git Bash (`/c/projects/...`), także ze spacjami (w cudzysłowie). Bez `--path` wybierany jest bieżący katalog. `--dir` oraz `--no-dir` wzajemnie się wykluczają. Bez `--dir` w trybie nieinteraktywnym (`--yes`) domyślnym katalogiem jest `public`. W kreatorze można wpisać `-`, aby zrezygnować z `-t`. **Ostrzeżenie:** `--no-dir` uruchamia PHP bez `-t`, czyli udostępnia katalog projektu. Może to prowadzić do ujawnienia przez HTTP plików `.env`, kopii zapasowych lub innych poufnych plików, jeśli serwer je udostępni. Preferuj `--dir public` i stosuj `--no-dir` tylko w projektach, w których cały katalog jest bezpieczny do udostępniania. Domyślnie przydzielany jest pierwszy nieprzypisany i aktualnie wolny port od 3000. +`--path` accepts Windows paths (`C:\projects\...`) and Git Bash paths (`/c/projects/...`), including paths containing spaces (quote them). Without `--path`, the current directory is used. `--dir` and `--no-dir` are mutually exclusive. In noninteractive mode (`--yes`), `public` is the default document root unless `--dir` or `--no-dir` is specified. In interactive mode, enter `-` to omit PHP's `-t` option. -## Polecenia +**Security warning:** `--no-dir` starts PHP without `-t` and serves the project directory. Depending on its contents and PHP server behavior, this may expose files such as `.env`, backups, or other sensitive resources over HTTP. Prefer `--dir public` and use `--no-dir` only when the entire directory is safe to serve. -| Polecenie | Znaczenie | +By default, the manager assigns the first unassigned, available port starting at 3000. + +## Commands + +| Command | Description | | --- | --- | -| `devserver add [NAZWA] [OPCJE]` | Kreator rejestracji projektu, opcjonalnie `--path`, `--dir` / `--no-dir`, `--port`, `--yes` | -| `devserver remove NAZWA` | Usuwa wpis z konfiguracji, nie usuwa plików | -| `devserver start NAZWA` | Uruchamia serwer | -| `devserver stop NAZWA` | Zatrzymuje zarządzany serwer | -| `devserver restart NAZWA` | Zatrzymuje i ponownie uruchamia | -| `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] [--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 | -| `devserver stop-all` | Zatrzymuje wszystkie zarządzane serwery | -| `devserver help [POLECENIE]` | Pomoc | -| `devserver -h`, `--help`, `/?` | Pomoc | -| `devserver --version` | Wyświetla numer wersji z pliku `VERSION` | - -Przykładowe wyjście `devserver list`: +| `devserver add [NAME] [OPTIONS]` | Register a project; supports `--path`, `--dir` / `--no-dir`, `--port`, `--yes` | +| `devserver remove NAME` | Remove the project from configuration without deleting its files | +| `devserver start NAME` | Start the project's server | +| `devserver stop NAME` | Stop the managed server | +| `devserver restart NAME` | Stop and start the server | +| `devserver list [--json]` | List projects, ports, document roots, process status, and uptime; optionally output JSON | +| `devserver status [--json]` | Backward-compatible alias for `list` | +| `devserver check NAME [--path /up] [--json]` | Perform an HTTP GET check (5-second timeout, no redirects); optionally output JSON | +| `devserver logs NAME [--lines N] [--stdout] [--follow]` | Read PHP logs (last 30 stderr lines by default) | +| `devserver edit NAME [OPTIONS]` | Change the project path, document root, or port (server must be stopped) | +| `devserver start-all` | Start all registered servers | +| `devserver stop-all` | Stop all managed servers | +| `devserver help [COMMAND]` | Show help | +| `devserver -h`, `--help`, `/?` | Show help | +| `devserver --version` | Display the version from `VERSION` | + +Example `devserver list` output (labels are emitted by the current CLI): ```text example-app | RUNNING | uptime: 2h 34m | http://127.0.0.1:3000 | C:\projects\example-app | WWW: public another-app | STOPPED | uptime: - | http://127.0.0.1:3001 | C:\projects\another-app | WWW: bez -t ``` -Stan RUNNING oznacza, że menedżer rozpoznaje własny proces PHP, nie że aplikacja pomyślnie odpowiada HTTP. Polecenie `status` jest nadal akceptowane jako alias, ale nie jest już osobno reklamowane w pomocy. +`RUNNING` means that the manager recognizes its PHP process, not that the application responds successfully to HTTP. `status` remains available as an alias of `list`, even though it is not listed separately in the CLI's general help. -W poleceniach `start`, `stop` i `restart` zamiast nazwy możesz użyć kropki (`.`), aby odwołać się do projektu zarejestrowanego dla bieżącego katalogu. +For `start`, `stop`, and `restart`, you may use a dot (`.`) instead of a name to address the project registered for your current directory. -## Uptime, diagnostyka HTTP i logi +## Uptime, HTTP diagnostics, and logs -Czas działania w `list` liczony jest od uruchomienia rozpoznanego procesu PHP. Nie oznacza czasu pracy aplikacji ani czasu od ostatniego żądania. Dla procesu zatrzymanego pokazuje `-`. `status` pozostaje aliasem `list`. +Uptime reported by `list` is calculated from the start time of the recognized PHP process. It does not represent application uptime or the time since the last request. Stopped processes display `-`. `status` is an alias of `list`. ```bash devserver check example-app @@ -135,7 +139,7 @@ devserver check example-app --path /up devserver check example-app --path /login ``` -`check` wysyła GET na `http://127.0.0.1:PORT/ścieżka`, bez przekierowań i z limitem 5 sekund. Wyświetla kod HTTP i czas odpowiedzi. Kody 404, 401 i 302 nadal oznaczają, że serwer odpowiedział. Kod 5xx lub błąd połączenia oznacza kod wyjścia 1. `--path` przyjmuje lokalną ścieżkę bez hosta oraz parametrów URL. +`check` sends a GET request to `http://127.0.0.1:PORT/path`, without following redirects, with a 5-second timeout. It reports the HTTP status code and response time. Responses such as 404, 401, and 302 still mean the server responded. An HTTP 5xx status or connection error results in exit code 1. The `--path` argument must be a local URL path, with no host or query string. ```bash devserver logs example-app @@ -144,9 +148,9 @@ devserver logs example-app --stdout devserver logs example-app --follow ``` -Domyślnie odczytywany jest plik `logs/example-app.err.log` (ostatnie 30 linii). `--stdout` przełącza na stdout, a `--follow` obserwuje dalsze wpisy do Ctrl+C. Menedżer nie czyści logów automatycznie. +By default, `logs` reads the last 30 lines of `logs/example-app.err.log`. Use `--stdout` to switch streams and `--follow` to follow new log entries until Ctrl+C. Logs are not automatically rotated or deleted. -## Edycja istniejącego projektu +## Editing a registered project ```bash devserver stop example-app @@ -156,29 +160,29 @@ devserver edit example-app --no-dir --yes devserver start example-app ``` -Bez `--yes` polecenie `edit` pyta o niewskazane wartości i proponuje aktualne ustawienia. `--yes` używa ich bez dodatkowych pytań. `--dir` i `--no-dir` wykluczają się wzajemnie. Sprawdzane są porty, ścieżki i duplikaty katalogów. Serwer musi być zatrzymany przed edycją. +Without `--yes`, `edit` prompts for unspecified settings and suggests their current values. With `--yes`, existing values are reused without prompting. `--dir` and `--no-dir` are mutually exclusive. Ports, paths, and duplicate project directories are validated. Stop a server before editing its configuration. -## Testy automatyczne na Windows +## Automated tests on Windows -Workflow `.github/workflows/windows-smoke.yml` sprawdza składnię PowerShell oraz scenariusze integracyjne na Windows z PHP CLI. Testy pracują w odrębnym katalogu tymczasowym, nie modyfikują projektów użytkownika. +The `.github/workflows/windows-smoke.yml` workflow checks PowerShell syntax and integration scenarios on Windows with PHP CLI. Tests use an isolated temporary directory and do not modify users' registered projects. ```powershell .\tests\smoke.ps1 ``` -Scenariusze obejmują pomoc, rejestrację, start/stop, uptime, HTTP, logi, edycję, walidację i usuwanie projektu. Wymagany jest `php.exe` w Windows PATH. Aktualny wynik testów jest widoczny w zakładce Actions na GitHubie. +Test scenarios include help, project registration, start/stop, uptime, HTTP and JSON diagnostics, logs, editing, validation, and project removal. `php.exe` must be on the Windows `PATH`. Current results are available in the GitHub Actions tab. -## Wersje i wydania +## Versioning and releases -Numer wersji przechowywany jest w pliku `VERSION` i wyświetlany przez `devserver --version`. Zmiany między wersjami opisuje [`CHANGELOG.md`](CHANGELOG.md). Stosujemy numerację [SemVer](https://semver.org/lang/pl/): `MAJOR.MINOR.PATCH`. Wersja `1.0.0` oznacza pierwszy stabilny zestaw poleceń CLI. Dalsze wydania będą wersjonowane zgodnie z zasadami SemVer. +The source version is stored in `VERSION` and displayed by `devserver --version`. Changes are recorded in [CHANGELOG.md](CHANGELOG.md). Releases follow [Semantic Versioning](https://semver.org/) (`MAJOR.MINOR.PATCH`). Version 1.0.0 established the initial stable CLI command set; subsequent releases follow SemVer compatibility rules. -Wydania oznaczamy tagami Git `vX.Y.Z` i publikujemy w GitHub Releases. Numer w `VERSION` identyfikuje kod, a tagi i wydania są publikowane osobno. +Releases are tagged `vX.Y.Z` and published using GitHub Releases. Updating `VERSION` does not create a Git tag or release automatically. See the [latest release](https://github.com/Tycjann/php-devserver-manager/releases/latest). -## Integracja z agentami AI (Cursor, Codex, Claude Code) +## AI agent integration (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. +Because the manager exposes a CLI, AI agents with access to a **local Windows terminal** can use it without a separate MCP server. The agent must have `devserver` on its Git Bash `PATH`, or call `devserver.ps1` using PowerShell. Commands run **on your computer**, not inside a remote isolated execution environment. Command approval and execution permissions depend on the agent's configuration. -### Odczyt maszynowy: `--json` +### Machine-readable output: `--json` ```bash devserver list --json @@ -186,7 +190,7 @@ devserver status --json devserver check example-app --path /up --json ``` -Przykład odpowiedzi `list --json` (dane przykładowe): +Example `list --json` response (illustrative values): ```json { @@ -207,9 +211,11 @@ Przykład odpowiedzi `list --json` (dane przykładowe): } ``` -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. +If there are no projects, `projects` is an empty array (`[]`). The `document_root`, `pid`, and `uptime_seconds` values may be `null`; port and uptime values are numeric when present. The `status` field is `RUNNING` or `STOPPED`. -Przykład odpowiedzi `check --json`: +**Privacy:** `path` contains a **local filesystem path**. Do not publish raw output containing private paths. + +Example `check --json` response: ```json { @@ -221,59 +227,70 @@ Przykład odpowiedzi `check --json`: } ``` -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. +`ok` indicates that the server responded with an HTTP status below 500. HTTP 4xx responses also produce `ok: true`: the server responded, even if the resource is unavailable. An HTTP 5xx response produces JSON with `ok: false` and exit code 1. Invalid arguments, a stopped server, or a connection error return an object such as `{"error":{"message":"..."}}` with exit code 1. Without `--json`, the existing text output is preserved. + +### Agent instructions -### Instrukcje dla agenta +Add the following instructions to the agent configuration in your application project. All three agents use the same underlying CLI commands: + +```text +Use PHP DevServer Manager to manage local PHP development servers. +First run devserver list --json; do not start a server that is already running. +For the current registered project, use devserver start . and devserver check . --json. +For errors, inspect devserver logs . --lines 50. +Do not register projects or stop other servers, including stop-all, without user approval. +Do not use --no-dir unless the served directory is confirmed safe for HTTP access. +Do not treat HTTP 200 as proof that the application works correctly. +Do not publish logs or list --json output without redacting private paths. +If devserver is unavailable, report it instead of changing the environment automatically. +``` -Wklej poniższe wskazówki do instrukcji wybranego agenta. Każdy agent korzysta z tych samych komend CLI: +**Cursor:** Put these instructions in a project rule such as `.cursor/rules/php-devserver.mdc` with YAML front matter: ```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ę. +--- +description: Local PHP development servers +alwaysApply: true +--- ``` -**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). +Then append the agent instructions above. See [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). +**Codex:** Add the instructions to `AGENTS.md` in the application project's root directory. See [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). +**Claude Code:** Add the instructions to `CLAUDE.md` in the application project's root directory. See [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. +Place agent instruction files in the **application project**, not the manager's directory. Local terminal access and permissions vary by editor and agent installation. -## Dane i kopie zapasowe +## Local data and backups ```text C:\projects\devserver\ -├── devserver # launcher Git Bash -├── devserver.ps1 # menedżer PowerShell -├── VERSION # numer wersji CLI -├── CHANGELOG.md # historia zmian +├── devserver # Git Bash launcher +├── devserver.ps1 # PowerShell manager +├── VERSION # CLI version +├── CHANGELOG.md # release history +├── README.md # English documentation +├── README.pl.md # Polish documentation ├── config\ -│ └── projects.json # lokalne ścieżki, porty, katalogi WWW +│ └── projects.json # local project paths, ports, document roots ├── logs\ # stderr/stdout -└── runtime\ # identyfikatory procesów +└── runtime\ # process identifiers ``` -Foldery `config/`, `logs/`, `runtime/` powstają w trakcie pracy. Repozytorium **nie śledzi** lokalnych danych. Do backupu wystarczy objąć nim w szczególności `config/projects.json`; `runtime` i `logs` można pominąć. Ścieżki projektów zapisujemy względem katalogu menedżera, gdy tylko jest to możliwe. +The `config/`, `logs/`, and `runtime/` directories are created while the manager runs. Git **does not track** local project configuration and runtime data. For backups, preserve at least `config/projects.json`; `runtime` and `logs` can usually be omitted. Project paths are stored relative to the manager directory when possible. -Logi serwerów trafiają do `logs/NAZWA.err.log` i `logs/NAZWA.out.log`. Nie umieszczaj menedżera w katalogu udostępnianym przez serwer HTTP, np. `public/`. +Server logs are written to `logs/NAME.err.log` and `logs/NAME.out.log`. Do not install the manager under an HTTP-served directory such as `public/`. -## Bezpieczeństwo i ograniczenia +## Security and limitations -- Nasłuch tylko na `127.0.0.1` (bez wystawiania serwera do sieci). -- `localhost` zwykle prowadzi do tego samego komputera, ale może wskazywać na `127.0.0.1` (IPv4) albo `::1` (IPv6), zależnie od konfiguracji systemu. Serwer nasłuchuje wyłącznie na `127.0.0.1`, dlatego dokumentacja konsekwentnie używa tego adresu. -- `stop` sprawdza PID oraz polecenie i ścieżkę pliku wykonywalnego przed zatrzymaniem procesu; nie wykonuje `taskkill` dla wszystkich procesów `php.exe`. -- `list` oraz jego alias `status` sprawdzają proces, a nie kondycję aplikacji. Do diagnostyki HTTP służy `check`. -- Gdy proces zarządzany zakończy się niespodziewanie, przy ponownym uruchomieniu nadpisywane są jego dane runtime. -- Przy uruchamianiu wielu serwerów z równoczesnymi żądaniami mogą ujawnić się ograniczenia wbudowanego serwera PHP. -- Wersja 1.0.0 nie zapewnia automatycznego startu systemowego ani centralnego panelu GUI. -- Automatyczne testy na Windows obejmują parser PowerShell i podstawowe scenariusze integracyjne. Tryb interaktywny (`Read-Host`) warto dodatkowo przetestować w lokalnym terminalu. +- The PHP server binds only to `127.0.0.1`, not external network interfaces. +- Depending on system configuration, `localhost` may resolve to `127.0.0.1` (IPv4) or `::1` (IPv6). The server listens only on `127.0.0.1`, so examples consistently use that address. +- Before stopping a server, the manager checks the PID, command line, and executable path. It does not run `taskkill` against every `php.exe` process. +- `list` and `status` report recognized processes, not application health. Use `check` for HTTP diagnostics. +- If a managed process exits unexpectedly, its runtime data is overwritten when started again. +- PHP's built-in server may have limitations under concurrent requests, even when several managed servers are running. +- The manager does not provide automatic startup on system boot or a centralized graphical interface. +- Automated Windows tests cover PowerShell parsing and basic integration scenarios. Interactive `Read-Host` behavior is also worth testing in a local terminal. -Licencja: [MIT](LICENSE). +License: [MIT](LICENSE). diff --git a/README.pl.md b/README.pl.md new file mode 100644 index 0000000..8a1f676 --- /dev/null +++ b/README.pl.md @@ -0,0 +1,281 @@ +# PHP DevServer Manager + +[English](README.md) | **Polski** + +Lekkie narzędzie CLI do zarządzania wieloma lokalnymi serwerami PHP w Windows i Git Bash. Umożliwia uruchamianie serwerów niezależnie od terminala, monitorowanie ich stanu, sprawdzanie odpowiedzi HTTP oraz przeglądanie logów. + +> **Wersja:** [najnowsze wydanie](https://github.com/Tycjann/php-devserver-manager/releases/latest) (wersja kodu: [`VERSION`](VERSION)). Pierwsze stabilne wydanie menedżera CLI zostało przetestowane automatycznie na Windows. Wbudowany serwer PHP służy wyłącznie do developmentu i nie jest przeznaczony do obsługi ruchu produkcyjnego. + +## Wymagania + +- Windows 10/11, PowerShell 5.1+ oraz Git Bash (Git for Windows). +- PHP CLI (`php.exe`) dostępny w **Windows PATH**, również z PowerShell. +- Uprawnienia do uruchamiania własnych procesów. Nie potrzeba uprawnień administratora. +- Polecenie `cygpath` dostępne w Git Bash. + +## Instalacja + +Przykładowa lokalizacja to `C:\projects\devserver`. Można wybrać dowolny katalog poza katalogiem udostępnianym przez serwer HTTP. + +Z Git Bash: + +```bash +mkdir -p /c/projects +cd /c/projects +git clone https://github.com/Tycjann/php-devserver-manager.git devserver +cd devserver +./devserver --help +./devserver --version +``` + +### Dostęp do polecenia z dowolnego katalogu (Git Bash) + +Żeby uruchamiać `devserver` bez prefiksu `./` z każdego katalogu projektu, dodaj katalog menedżera do zmiennej `PATH` w Git Bash. W poniższych przykładach menedżer znajduje się w `C:\projects\devserver`; dostosuj ścieżkę do własnej instalacji. + +1. Otwórz plik konfiguracyjny powłoki: + + ```bash + nano ~/.bashrc + ``` + +2. Dodaj na końcu pliku: + + ```bash + export PATH="/c/projects/devserver:$PATH" + ``` + +3. Zapisz plik, a następnie wczytaj ustawienia i sprawdź, czy polecenie jest dostępne: + + ```bash + source ~/.bashrc + command -v devserver + ``` + + Oczekiwany wynik dla przykładowej lokalizacji: `/c/projects/devserver/devserver`. + +Od tej chwili można uruchamiać `devserver list` z dowolnego katalogu. Polecenia `devserver start .`, `devserver stop .` i `devserver restart .` korzystają z bieżącego katalogu, jeżeli jest on zarejestrowany jako projekt. + +Jeżeli pojawi się `Permission denied`, nadaj uprawnienie wykonywania launcherowi (`chmod +x /c/projects/devserver/devserver`) lub wywołuj go przez `bash /c/projects/devserver/devserver ...`. + +Ustawienie `~/.bashrc` dotyczy Git Bash, nie dodaje automatycznie polecenia do PowerShell ani CMD. + +## Pierwsze uruchomienie + +Rejestracja może być interaktywna. Uruchom `devserver add`, aby odpowiedzieć na pytania o nazwę, lokalizację, katalog WWW i port. Naciśnięcie Enter akceptuje proponowaną wartość. Parametry podane w poleceniu nie są ponownie zadawane. `--yes` całkowicie pomija pytania, co przydaje się agentom AI. + +Przykładowy kreator: + +```text +$ devserver add +Nazwa projektu [example-app]: +Sciezka projektu [C:\projects\example-app]: +Katalog WWW (- = bez -t) [public]: - +Port serwera [3000]: +``` + +Przejdź do katalogu aplikacji (nie do `public`): + +```bash +cd /c/projects/example-app +devserver add example-app # port automatyczny, katalog public +devserver start example-app +devserver list +``` + +Opcje można łączyć w dowolnej kolejności: + +```bash +devserver add website --dir htdocs --port 3010 +devserver add test --port 3020 --no-dir +devserver add api --port 3030 --dir web +devserver add example-app --path "/c/projects/example-app" --port 3000 +devserver add sample-bot --path "/c/projects/test" --no-dir --yes +``` + +`--path` przyjmuje ścieżkę Windows (`C:\\projects\\...`) lub Git Bash (`/c/projects/...`), także ze spacjami (w cudzysłowie). Bez `--path` wybierany jest bieżący katalog. `--dir` oraz `--no-dir` wzajemnie się wykluczają. Bez `--dir` w trybie nieinteraktywnym (`--yes`) domyślnym katalogiem jest `public`. W kreatorze można wpisać `-`, aby zrezygnować z `-t`. **Ostrzeżenie:** `--no-dir` uruchamia PHP bez `-t`, czyli udostępnia katalog projektu. Może to prowadzić do ujawnienia przez HTTP plików `.env`, kopii zapasowych lub innych poufnych plików, jeśli serwer je udostępni. Preferuj `--dir public` i stosuj `--no-dir` tylko w projektach, w których cały katalog jest bezpieczny do udostępniania. Domyślnie przydzielany jest pierwszy nieprzypisany i aktualnie wolny port od 3000. + +## Polecenia + +| Polecenie | Znaczenie | +| --- | --- | +| `devserver add [NAZWA] [OPCJE]` | Kreator rejestracji projektu, opcjonalnie `--path`, `--dir` / `--no-dir`, `--port`, `--yes` | +| `devserver remove NAZWA` | Usuwa wpis z konfiguracji, nie usuwa plików | +| `devserver start NAZWA` | Uruchamia serwer | +| `devserver stop NAZWA` | Zatrzymuje zarządzany serwer | +| `devserver restart NAZWA` | Zatrzymuje i ponownie uruchamia | +| `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] [--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 | +| `devserver stop-all` | Zatrzymuje wszystkie zarządzane serwery | +| `devserver help [POLECENIE]` | Pomoc | +| `devserver -h`, `--help`, `/?` | Pomoc | +| `devserver --version` | Wyświetla numer wersji z pliku `VERSION` | + +Przykładowe wyjście `devserver list`: + +```text +example-app | RUNNING | uptime: 2h 34m | http://127.0.0.1:3000 | C:\projects\example-app | WWW: public +another-app | STOPPED | uptime: - | http://127.0.0.1:3001 | C:\projects\another-app | WWW: bez -t +``` + +Stan RUNNING oznacza, że menedżer rozpoznaje własny proces PHP, nie że aplikacja pomyślnie odpowiada HTTP. Polecenie `status` jest nadal akceptowane jako alias, ale nie jest już osobno reklamowane w pomocy. + +W poleceniach `start`, `stop` i `restart` zamiast nazwy możesz użyć kropki (`.`), aby odwołać się do projektu zarejestrowanego dla bieżącego katalogu. + +## Uptime, diagnostyka HTTP i logi + +Czas działania w `list` liczony jest od uruchomienia rozpoznanego procesu PHP. Nie oznacza czasu pracy aplikacji ani czasu od ostatniego żądania. Dla procesu zatrzymanego pokazuje `-`. `status` pozostaje aliasem `list`. + +```bash +devserver check example-app +devserver check example-app --path /up +devserver check example-app --path /login +``` + +`check` wysyła GET na `http://127.0.0.1:PORT/ścieżka`, bez przekierowań i z limitem 5 sekund. Wyświetla kod HTTP i czas odpowiedzi. Kody 404, 401 i 302 nadal oznaczają, że serwer odpowiedział. Kod 5xx lub błąd połączenia oznacza kod wyjścia 1. `--path` przyjmuje lokalną ścieżkę bez hosta oraz parametrów URL. + +```bash +devserver logs example-app +devserver logs example-app --lines 100 +devserver logs example-app --stdout +devserver logs example-app --follow +``` + +Domyślnie odczytywany jest plik `logs/example-app.err.log` (ostatnie 30 linii). `--stdout` przełącza na stdout, a `--follow` obserwuje dalsze wpisy do Ctrl+C. Menedżer nie czyści logów automatycznie. + +## Edycja istniejącego projektu + +```bash +devserver stop example-app +devserver edit example-app +devserver edit example-app --path "/c/projects/example-app" --dir public --port 3005 --yes +devserver edit example-app --no-dir --yes +devserver start example-app +``` + +Bez `--yes` polecenie `edit` pyta o niewskazane wartości i proponuje aktualne ustawienia. `--yes` używa ich bez dodatkowych pytań. `--dir` i `--no-dir` wykluczają się wzajemnie. Sprawdzane są porty, ścieżki i duplikaty katalogów. Serwer musi być zatrzymany przed edycją. + +## Testy automatyczne na Windows + +Workflow `.github/workflows/windows-smoke.yml` sprawdza składnię PowerShell oraz scenariusze integracyjne na Windows z PHP CLI. Testy pracują w odrębnym katalogu tymczasowym, nie modyfikują projektów użytkownika. + +```powershell +.\tests\smoke.ps1 +``` + +Scenariusze obejmują pomoc, rejestrację, start/stop, uptime, HTTP, logi, edycję, walidację i usuwanie projektu. Wymagany jest `php.exe` w Windows PATH. Aktualny wynik testów jest widoczny w zakładce Actions na GitHubie. + +## Wersje i wydania + +Numer wersji przechowywany jest w pliku `VERSION` i wyświetlany przez `devserver --version`. Zmiany między wersjami opisuje [`CHANGELOG.md`](CHANGELOG.md). Stosujemy numerację [SemVer](https://semver.org/lang/pl/): `MAJOR.MINOR.PATCH`. Wersja `1.0.0` oznacza pierwszy stabilny zestaw poleceń CLI. Dalsze wydania będą wersjonowane zgodnie z zasadami SemVer. + +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 +C:\projects\devserver\ +├── devserver # launcher Git Bash +├── devserver.ps1 # menedżer PowerShell +├── VERSION # numer wersji CLI +├── CHANGELOG.md # historia zmian +├── README.md # dokumentacja angielska +├── README.pl.md # dokumentacja polska +├── config\ +│ └── projects.json # lokalne ścieżki, porty, katalogi WWW +├── logs\ # stderr/stdout +└── runtime\ # identyfikatory procesów +``` + +Foldery `config/`, `logs/`, `runtime/` powstają w trakcie pracy. Repozytorium **nie śledzi** lokalnych danych. Do backupu wystarczy objąć nim w szczególności `config/projects.json`; `runtime` i `logs` można pominąć. Ścieżki projektów zapisujemy względem katalogu menedżera, gdy tylko jest to możliwe. + +Logi serwerów trafiają do `logs/NAZWA.err.log` i `logs/NAZWA.out.log`. Nie umieszczaj menedżera w katalogu udostępnianym przez serwer HTTP, np. `public/`. + +## Bezpieczeństwo i ograniczenia + +- Nasłuch tylko na `127.0.0.1` (bez wystawiania serwera do sieci). +- `localhost` zwykle prowadzi do tego samego komputera, ale może wskazywać na `127.0.0.1` (IPv4) albo `::1` (IPv6), zależnie od konfiguracji systemu. Serwer nasłuchuje wyłącznie na `127.0.0.1`, dlatego dokumentacja konsekwentnie używa tego adresu. +- `stop` sprawdza PID oraz polecenie i ścieżkę pliku wykonywalnego przed zatrzymaniem procesu; nie wykonuje `taskkill` dla wszystkich procesów `php.exe`. +- `list` oraz jego alias `status` sprawdzają proces, a nie kondycję aplikacji. Do diagnostyki HTTP służy `check`. +- Gdy proces zarządzany zakończy się niespodziewanie, przy ponownym uruchomieniu nadpisywane są jego dane runtime. +- Przy uruchamianiu wielu serwerów z równoczesnymi żądaniami mogą ujawnić się ograniczenia wbudowanego serwera PHP. +- Narzędzie nie zapewnia automatycznego startu systemowego ani centralnego panelu GUI. +- Automatyczne testy na Windows obejmują parser PowerShell i podstawowe scenariusze integracyjne. Tryb interaktywny (`Read-Host`) warto dodatkowo przetestować w lokalnym terminalu. + +Licencja: [MIT](LICENSE).