core/go
8
0
Fork 0
generated from lthn/LEM
Code Issues 2 Pull requests 1 Projects Releases Packages Wiki Activity Actions

docs: sync php, pkg, setup, doctor, test with CLI

Browse source 
- 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 <noreply@anthropic.com>
This commit is contained in:
Snider 2026-01-29 16:26:27 +00:00
parent ea9d735a99
commit 78cb2b3507
7 changed files with 209 additions and 117 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

52
docs/cmd/TODO.md
View file

@ -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`

8
docs/cmd/doctor/index.md
View file

@ -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

98
docs/cmd/php/index.md
View file

@ -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>
```
| 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

42
docs/cmd/pkg/index.md
View file

@ -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 <command> [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 <query> [flags]
```
See [search](search/) for details.
## pkg install
Install a Go module.
Clone a package from GitHub.
```bash
core pkg install <module> [flags]
core pkg install <repo> [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.

11
docs/cmd/setup/example.md
View file

@ -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

42
docs/cmd/setup/index.md
View file

@ -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

73
docs/cmd/test/index.md
View file

@ -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