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. 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 ## 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 ### core pkg search
- `--refresh` - Bypass cache and fetch fresh data - `--refresh` - Bypass cache and fetch fresh data
- `--type` - Filter by type in name (mod, services, plug, website) - `--type` - Filter by type in name (mod, services, plug, website)
### core pkg install
- `--add` - Add to repos.yaml registry
### core vm run ### core vm run
- `--ssh-port` - SSH port for exec commands (default: 2222) - `--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` - 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` - 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 ## Usage
```bash ```bash
core doctor core doctor [flags]
``` ```
## Flags
| Flag | Description |
|------|-------------|
| `--verbose` | Show detailed version information |
## What It Checks ## What It Checks
### Required Tools ### Required Tools

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

@ -1,18 +1,27 @@
# core php # core php
Laravel/PHP development environment with FrankenPHP, Vite, Horizon, Reverb, and Redis. Laravel/PHP development tools with FrankenPHP.
## Commands ## Commands
| Command | Description | | Command | Description |
|---------|-------------| |---------|-------------|
| `core php dev` | Start development environment | | `dev` | Start development environment |
| `core php test` | Run PHPUnit/Pest tests | | `logs` | View service logs |
| `core php fmt` | Format with Laravel Pint | | `stop` | Stop all services |
| `core php analyse` | Static analysis with PHPStan | | `status` | Show service status |
| `core php build` | Build production container | | `ssl` | Setup SSL certificates with mkcert |
| `core php deploy` | Deploy to Coolify | | `build` | Build Docker or LinuxKit image |
| `core php ssl` | Setup SSL certificates | | `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 ## Development Environment
@ -21,17 +30,20 @@ Laravel/PHP development environment with FrankenPHP, Vite, Horizon, Reverb, and
core php dev core php dev
``` ```
This starts: Services orchestrated:
- FrankenPHP/Octane (HTTP server) - FrankenPHP/Octane (port 8000, HTTPS on 443)
- Vite dev server (frontend) - Vite dev server (port 5173)
- Laravel Horizon (queues) - Laravel Horizon (queue workers)
- Laravel Reverb (WebSockets) - Laravel Reverb (WebSocket, port 8080)
- Redis - Redis (port 6379)
```bash ```bash
# View unified logs # View unified logs
core php logs core php logs
# Check service status
core php status
# Stop all services # Stop all services
core php stop core php stop
``` ```
@ -57,12 +69,9 @@ core php fmt
# Static analysis # Static analysis
core php analyse core php analyse
# Run both
core php fmt && core php analyse
``` ```
## Building ## Building & Serving
```bash ```bash
# Build Docker container # Build Docker container
@ -70,9 +79,34 @@ core php build
# Build LinuxKit image # Build LinuxKit image
core php build --type linuxkit core php build --type linuxkit
```
# Run production locally ### php serve
core php serve --production
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 ## Deployment
@ -90,18 +124,37 @@ core php deploy --wait
# Check deployment status # Check deployment status
core php deploy:status core php deploy:status
# List recent deployments
core php deploy:list
# Rollback # Rollback
core php deploy:rollback core php deploy:rollback
``` ```
## Package Management ## 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 ```bash
# Link a local package # Link a local package
core php packages link ../my-package core php packages link ../my-package
# List linked packages
core php packages list
# Update linked packages # Update linked packages
core php packages update core php packages update
@ -114,8 +167,7 @@ core php packages unlink my-package
Local SSL with mkcert: Local SSL with mkcert:
```bash ```bash
# Auto-configured with core php dev core php ssl
# Uses mkcert for trusted local certificates
``` ```
## Configuration ## Configuration

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

@ -1,6 +1,6 @@
# core pkg # core pkg
Package management for Go modules. Package management for host-uk/core-* repos.
## Usage ## Usage
@ -12,25 +12,41 @@ core pkg <command> [flags]
| Command | Description | | Command | Description |
|---------|-------------| |---------|-------------|
| [search](search/) | Search packages on GitHub | | [search](search/) | Search GitHub for packages |
| `install` | Install a package | | `install` | Clone a package from GitHub |
| `list` | List installed packages | | `list` | List installed packages |
| `update` | Update packages | | `update` | Update installed packages |
| `outdated` | Check for outdated 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 ## pkg install
Install a Go module. Clone a package from GitHub.
```bash ```bash
core pkg install <module> [flags] core pkg install <repo> [flags]
``` ```
### Flags
| Flag | Description |
|------|-------------|
| `--add` | Add to repos.yaml registry |
### Examples ### Examples
```bash ```bash
core pkg install github.com/host-uk/core-php core pkg install core-php
core pkg install github.com/spf13/cobra@latest core pkg install core-tenant --add
``` ```
## pkg list ## pkg list
@ -43,18 +59,12 @@ core pkg list
## pkg update ## pkg update
Update packages to latest versions. Update installed packages.
```bash ```bash
core pkg update [flags] core pkg update
``` ```
### Flags
| Flag | Description |
|------|-------------|
| `--all` | Update all packages |
## pkg outdated ## pkg outdated
Check for outdated packages. Check for outdated packages.

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

@ -4,11 +4,14 @@
# Clone all repos # Clone all repos
core setup core setup
# Specific directory # Preview what would be cloned
core setup --path ~/Code/host-uk core setup --dry-run
# Use SSH # Only foundation packages
core setup --ssh core setup --only foundation
# Multiple types
core setup --only foundation,module
``` ```
## Configuration ## Configuration

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

@ -2,6 +2,8 @@
Clone all repositories from the registry. Clone all repositories from the registry.
Clones all repositories defined in repos.yaml into packages/. Skips repos that already exist.
## Usage ## Usage
```bash ```bash
@ -12,9 +14,9 @@ core setup [flags]
| Flag | Description | | Flag | Description |
|------|-------------| |------|-------------|
| `--registry` | Path to repos.yaml | | `--registry` | Path to repos.yaml (auto-detected if not specified) |
| `--path` | Base directory for cloning (default: current dir) | | `--dry-run` | Show what would be cloned without cloning |
| `--ssh` | Use SSH URLs instead of HTTPS | | `--only` | Only clone repos of these types (comma-separated: foundation,module,product) |
## Examples ## Examples
@ -22,11 +24,14 @@ core setup [flags]
# Clone all repos from registry # Clone all repos from registry
core setup core setup
# Clone to specific directory # Preview what would be cloned
core setup --path ~/Code/host-uk core setup --dry-run
# Use SSH for cloning # Only clone foundation packages
core setup --ssh core setup --only foundation
# Clone specific types
core setup --only foundation,module
``` ```
## Registry Format ## Registry Format
@ -35,21 +40,20 @@ The registry file (`repos.yaml`) defines repositories:
```yaml ```yaml
repos: repos:
- name: core core:
type: foundation
url: https://github.com/host-uk/core url: https://github.com/host-uk/core
description: Go CLI for the host-uk ecosystem description: Go CLI for the host-uk ecosystem
- name: core-php core-php:
type: foundation
url: https://github.com/host-uk/core-php url: https://github.com/host-uk/core-php
description: PHP/Laravel packages description: PHP/Laravel packages
- name: core-images core-tenant:
url: https://github.com/host-uk/core-images type: module
description: Docker and LinuxKit images url: https://github.com/host-uk/core-tenant
description: Multi-tenancy module
- name: core-api
url: https://github.com/host-uk/core-api
description: API service
``` ```
## Output ## Output
@ -60,10 +64,10 @@ Setting up host-uk workspace...
Cloning repositories: Cloning repositories:
[1/4] core............... ✓ [1/4] core............... ✓
[2/4] core-php........... ✓ [2/4] core-php........... ✓
[3/4] core-images........ ✓ [3/4] core-tenant........ ✓
[4/4] core-api........... ✓ [4/4] core-admin......... ✓
Done! 4 repositories cloned to ~/Code/host-uk Done! 4 repositories cloned to packages/
``` ```
## Finding Registry ## Finding Registry

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

@ -1,5 +1,74 @@
# core test # 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