From 78cb2b3507d481025068f6ab41d2c7b6ffd787c7 Mon Sep 17 00:00:00 2001 From: Snider Date: Thu, 29 Jan 2026 16:26:27 +0000 Subject: [PATCH] docs: sync php, pkg, setup, doctor, test with CLI - php: add serve flags, packages subcommands, all commands - pkg: fix description (GitHub repos not Go modules), add --add flag - setup: replace --path/--ssh with --dry-run/--only - doctor: add --verbose flag - test: full documentation with all flags and JSON output - Cleaned up TODO.md Co-Authored-By: Claude Opus 4.5 --- docs/cmd/TODO.md | 52 --------------------- docs/cmd/doctor/index.md | 8 +++- docs/cmd/php/index.md | 98 ++++++++++++++++++++++++++++++--------- docs/cmd/pkg/index.md | 42 ++++++++++------- docs/cmd/setup/example.md | 11 +++-- docs/cmd/setup/index.md | 42 +++++++++-------- docs/cmd/test/index.md | 73 ++++++++++++++++++++++++++++- 7 files changed, 209 insertions(+), 117 deletions(-) diff --git a/docs/cmd/TODO.md b/docs/cmd/TODO.md index 72742dcb..c24d6f34 100644 --- a/docs/cmd/TODO.md +++ b/docs/cmd/TODO.md @@ -2,52 +2,13 @@ Commands and flags found in CLI but missing from documentation. -## Missing Commands - -### core php - -- `core php packages link` - Link local packages (subcommand documentation exists but not detailed) -- `core php packages unlink` - Unlink packages -- `core php packages update` - Update linked packages -- `core php packages list` - List linked packages - -### core vm - -- `core vm templates show` - Display template content -- `core vm templates vars` - Show template variables - ## Missing Flags -### core setup - -- `--dry-run` - Show what would be cloned without cloning -- `--only` - Only clone repos of these types (comma-separated: foundation,module,product) -- Docs mention `--path` and `--ssh` which are not in CLI - -### core doctor - -- `--verbose` - Show detailed version information - -### core test - -- All flags are missing from the minimal docs page: - - `--coverage` - Show detailed per-package coverage - - `--json` - Output JSON for CI/agents - - `--pkg` - Package pattern to test - - `--race` - Enable race detector - - `--run` - Run only tests matching this regex - - `--short` - Skip long-running tests - - `--verbose` - Show test output as it runs - ### core pkg search - `--refresh` - Bypass cache and fetch fresh data - `--type` - Filter by type in name (mod, services, plug, website) -### core pkg install - -- `--add` - Add to repos.yaml registry - ### core vm run - `--ssh-port` - SSH port for exec commands (default: 2222) @@ -58,16 +19,3 @@ Commands and flags found in CLI but missing from documentation. - Docs describe `core sdk generate` command but CLI only has `core sdk diff` and `core sdk validate` - SDK generation is actually at `core build sdk`, not `core sdk generate` - -### core setup - -- Docs mention `--path` and `--ssh` flags but CLI has `--dry-run` and `--only` flags instead - -### core pkg - -- Docs describe package management for "Go modules" but CLI help says it's for "core-* repos" (GitHub repos) -- `core pkg install` works differently: docs show Go module paths, CLI shows GitHub repo format - -### core php serve - -- Docs mention `--production` flag but CLI has different flags: `--name`, `--tag`, `--port`, `--https-port`, `-d`, `--env-file`, `--container` diff --git a/docs/cmd/doctor/index.md b/docs/cmd/doctor/index.md index a8c2b05e..02cc44d6 100644 --- a/docs/cmd/doctor/index.md +++ b/docs/cmd/doctor/index.md @@ -5,9 +5,15 @@ Check your development environment for required tools and configuration. ## Usage ```bash -core doctor +core doctor [flags] ``` +## Flags + +| Flag | Description | +|------|-------------| +| `--verbose` | Show detailed version information | + ## What It Checks ### Required Tools diff --git a/docs/cmd/php/index.md b/docs/cmd/php/index.md index 254c1288..ec1503ae 100644 --- a/docs/cmd/php/index.md +++ b/docs/cmd/php/index.md @@ -1,18 +1,27 @@ # core php -Laravel/PHP development environment with FrankenPHP, Vite, Horizon, Reverb, and Redis. +Laravel/PHP development tools with FrankenPHP. ## Commands | Command | Description | |---------|-------------| -| `core php dev` | Start development environment | -| `core php test` | Run PHPUnit/Pest tests | -| `core php fmt` | Format with Laravel Pint | -| `core php analyse` | Static analysis with PHPStan | -| `core php build` | Build production container | -| `core php deploy` | Deploy to Coolify | -| `core php ssl` | Setup SSL certificates | +| `dev` | Start development environment | +| `logs` | View service logs | +| `stop` | Stop all services | +| `status` | Show service status | +| `ssl` | Setup SSL certificates with mkcert | +| `build` | Build Docker or LinuxKit image | +| `serve` | Run production container | +| `shell` | Open shell in running container | +| `test` | Run PHP tests (PHPUnit/Pest) | +| `fmt` | Format code with Laravel Pint | +| `analyse` | Run PHPStan static analysis | +| `packages` | Manage local PHP packages | +| `deploy` | Deploy to Coolify | +| `deploy:status` | Show deployment status | +| `deploy:rollback` | Rollback to previous deployment | +| `deploy:list` | List recent deployments | ## Development Environment @@ -21,17 +30,20 @@ Laravel/PHP development environment with FrankenPHP, Vite, Horizon, Reverb, and core php dev ``` -This starts: -- FrankenPHP/Octane (HTTP server) -- Vite dev server (frontend) -- Laravel Horizon (queues) -- Laravel Reverb (WebSockets) -- Redis +Services orchestrated: +- FrankenPHP/Octane (port 8000, HTTPS on 443) +- Vite dev server (port 5173) +- Laravel Horizon (queue workers) +- Laravel Reverb (WebSocket, port 8080) +- Redis (port 6379) ```bash # View unified logs core php logs +# Check service status +core php status + # Stop all services core php stop ``` @@ -57,12 +69,9 @@ core php fmt # Static analysis core php analyse - -# Run both -core php fmt && core php analyse ``` -## Building +## Building & Serving ```bash # Build Docker container @@ -70,9 +79,34 @@ core php build # Build LinuxKit image core php build --type linuxkit +``` -# Run production locally -core php serve --production +### php serve + +Run a production container. + +```bash +core php serve [flags] +``` + +#### Flags + +| Flag | Description | +|------|-------------| +| `--name` | Docker image name (required) | +| `--tag` | Image tag (default: latest) | +| `--port` | HTTP port (default: 80) | +| `--https-port` | HTTPS port (default: 443) | +| `-d` | Run in detached mode | +| `--env-file` | Path to environment file | +| `--container` | Container name | + +#### Examples + +```bash +core php serve --name myapp +core php serve --name myapp -d +core php serve --name myapp --port 8080 ``` ## Deployment @@ -90,18 +124,37 @@ core php deploy --wait # Check deployment status core php deploy:status +# List recent deployments +core php deploy:list + # Rollback core php deploy:rollback ``` ## Package Management -Link local packages for development: +Link local packages for development (similar to npm link). + +```bash +core php packages +``` + +| Command | Description | +|---------|-------------| +| `link` | Link local packages by path | +| `unlink` | Unlink packages by name | +| `update` | Update linked packages | +| `list` | List linked packages | + +### Examples ```bash # Link a local package core php packages link ../my-package +# List linked packages +core php packages list + # Update linked packages core php packages update @@ -114,8 +167,7 @@ core php packages unlink my-package Local SSL with mkcert: ```bash -# Auto-configured with core php dev -# Uses mkcert for trusted local certificates +core php ssl ``` ## Configuration diff --git a/docs/cmd/pkg/index.md b/docs/cmd/pkg/index.md index e801bb4d..581460d9 100644 --- a/docs/cmd/pkg/index.md +++ b/docs/cmd/pkg/index.md @@ -1,6 +1,6 @@ # core pkg -Package management for Go modules. +Package management for host-uk/core-* repos. ## Usage @@ -12,25 +12,41 @@ core pkg [flags] | Command | Description | |---------|-------------| -| [search](search/) | Search packages on GitHub | -| `install` | Install a package | +| [search](search/) | Search GitHub for packages | +| `install` | Clone a package from GitHub | | `list` | List installed packages | -| `update` | Update packages | +| `update` | Update installed packages | | `outdated` | Check for outdated packages | +## pkg search + +Search GitHub for host-uk packages. + +```bash +core pkg search [flags] +``` + +See [search](search/) for details. + ## pkg install -Install a Go module. +Clone a package from GitHub. ```bash -core pkg install [flags] +core pkg install [flags] ``` +### Flags + +| Flag | Description | +|------|-------------| +| `--add` | Add to repos.yaml registry | + ### Examples ```bash -core pkg install github.com/host-uk/core-php -core pkg install github.com/spf13/cobra@latest +core pkg install core-php +core pkg install core-tenant --add ``` ## pkg list @@ -43,18 +59,12 @@ core pkg list ## pkg update -Update packages to latest versions. +Update installed packages. ```bash -core pkg update [flags] +core pkg update ``` -### Flags - -| Flag | Description | -|------|-------------| -| `--all` | Update all packages | - ## pkg outdated Check for outdated packages. diff --git a/docs/cmd/setup/example.md b/docs/cmd/setup/example.md index 437c5983..ab13d07e 100644 --- a/docs/cmd/setup/example.md +++ b/docs/cmd/setup/example.md @@ -4,11 +4,14 @@ # Clone all repos core setup -# Specific directory -core setup --path ~/Code/host-uk +# Preview what would be cloned +core setup --dry-run -# Use SSH -core setup --ssh +# Only foundation packages +core setup --only foundation + +# Multiple types +core setup --only foundation,module ``` ## Configuration diff --git a/docs/cmd/setup/index.md b/docs/cmd/setup/index.md index a9bb6eba..e1c23df6 100644 --- a/docs/cmd/setup/index.md +++ b/docs/cmd/setup/index.md @@ -2,6 +2,8 @@ Clone all repositories from the registry. +Clones all repositories defined in repos.yaml into packages/. Skips repos that already exist. + ## Usage ```bash @@ -12,9 +14,9 @@ core setup [flags] | Flag | Description | |------|-------------| -| `--registry` | Path to repos.yaml | -| `--path` | Base directory for cloning (default: current dir) | -| `--ssh` | Use SSH URLs instead of HTTPS | +| `--registry` | Path to repos.yaml (auto-detected if not specified) | +| `--dry-run` | Show what would be cloned without cloning | +| `--only` | Only clone repos of these types (comma-separated: foundation,module,product) | ## Examples @@ -22,11 +24,14 @@ core setup [flags] # Clone all repos from registry core setup -# Clone to specific directory -core setup --path ~/Code/host-uk +# Preview what would be cloned +core setup --dry-run -# Use SSH for cloning -core setup --ssh +# Only clone foundation packages +core setup --only foundation + +# Clone specific types +core setup --only foundation,module ``` ## Registry Format @@ -35,21 +40,20 @@ The registry file (`repos.yaml`) defines repositories: ```yaml repos: - - name: core + core: + type: foundation url: https://github.com/host-uk/core description: Go CLI for the host-uk ecosystem - - name: core-php + core-php: + type: foundation url: https://github.com/host-uk/core-php description: PHP/Laravel packages - - name: core-images - url: https://github.com/host-uk/core-images - description: Docker and LinuxKit images - - - name: core-api - url: https://github.com/host-uk/core-api - description: API service + core-tenant: + type: module + url: https://github.com/host-uk/core-tenant + description: Multi-tenancy module ``` ## Output @@ -60,10 +64,10 @@ Setting up host-uk workspace... Cloning repositories: [1/4] core............... ✓ [2/4] core-php........... ✓ - [3/4] core-images........ ✓ - [4/4] core-api........... ✓ + [3/4] core-tenant........ ✓ + [4/4] core-admin......... ✓ -Done! 4 repositories cloned to ~/Code/host-uk +Done! 4 repositories cloned to packages/ ``` ## Finding Registry diff --git a/docs/cmd/test/index.md b/docs/cmd/test/index.md index dbf2b2ce..920baeac 100644 --- a/docs/cmd/test/index.md +++ b/docs/cmd/test/index.md @@ -1,5 +1,74 @@ # core test -Run tests (legacy command). +Run Go tests with coverage reporting. -**Prefer:** `core go test` or `core php test` +Sets `MACOSX_DEPLOYMENT_TARGET=26.0` to suppress linker warnings on macOS. + +## Usage + +```bash +core test [flags] +``` + +## Flags + +| Flag | Description | +|------|-------------| +| `--coverage` | Show detailed per-package coverage | +| `--json` | Output JSON for CI/agents | +| `--pkg` | Package pattern to test (default: ./...) | +| `--race` | Enable race detector | +| `--run` | Run only tests matching this regex | +| `--short` | Skip long-running tests | +| `--verbose` | Show test output as it runs | + +## Examples + +```bash +# Run all tests with coverage summary +core test + +# Show test output as it runs +core test --verbose + +# Detailed per-package coverage +core test --coverage + +# Test specific packages +core test --pkg ./pkg/... + +# Run specific test by name +core test --run TestName + +# Run tests matching pattern +core test --run "Test.*Good" + +# Skip long-running tests +core test --short + +# Enable race detector +core test --race + +# Output JSON for CI/agents +core test --json +``` + +## JSON Output + +With `--json`, outputs structured results: + +```json +{ + "passed": 14, + "failed": 0, + "skipped": 0, + "coverage": 75.1, + "exit_code": 0, + "failed_packages": [] +} +``` + +## See Also + +- [go test](../go/test/) - Go-specific test options +- [go cov](../go/cov/) - Coverage reports