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

docs: add comprehensive CLI documentation

Browse source 
- Add sdk.md: SDK generation and API diff commands
- Add dev.md: DevOps portable environment (100+ tools)
- Add doctor.md: Environment health check
- Add search.md: GitHub search and install commands
- Update build.md: Add code signing flags (--no-sign, --notarize)
- Update release.md: Add --target sdk flag
- Update index.md: Organize commands by category

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
Snider 2026-01-29 09:34:57 +00:00
parent 032e5ae4cc
commit 229cde534d
7 changed files with 825 additions and 4 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

58
docs/build.md
View file

@ -17,6 +17,8 @@ core build [flags]
| `--output` | Output directory (default: `dist`) |
| `--ci` | CI mode - non-interactive, fail fast |
| `--image` | Docker image name (for docker builds) |
| `--no-sign` | Skip code signing |
| `--notarize` | Enable macOS notarization (requires Apple credentials) |
## Examples
@ -110,4 +112,60 @@ targets:
arch: arm64
- os: darwin
arch: arm64
sign:
enabled: true
gpg:
key: $GPG_KEY_ID
macos:
identity: "Developer ID Application: Your Name (TEAM_ID)"
notarize: false
apple_id: $APPLE_ID
team_id: $APPLE_TEAM_ID
app_password: $APPLE_APP_PASSWORD
```
## Code Signing
Core supports GPG signing for checksums and native code signing for macOS.
### GPG Signing
Signs `CHECKSUMS.txt` with a detached ASCII signature (`.asc`):
```bash
# Build with GPG signing (default if key configured)
core build
# Skip signing
core build --no-sign
```
Users can verify:
```bash
gpg --verify CHECKSUMS.txt.asc CHECKSUMS.txt
sha256sum -c CHECKSUMS.txt
```
### macOS Code Signing
Signs Darwin binaries with your Developer ID and optionally notarizes with Apple:
```bash
# Build with codesign (automatic if identity configured)
core build
# Build with notarization (takes 1-5 minutes)
core build --notarize
```
### Environment Variables
| Variable | Purpose |
|----------|---------|
| `GPG_KEY_ID` | GPG key ID or fingerprint |
| `CODESIGN_IDENTITY` | macOS Developer ID (fallback) |
| `APPLE_ID` | Apple account email |
| `APPLE_TEAM_ID` | Apple Developer Team ID |
| `APPLE_APP_PASSWORD` | App-specific password for notarization |

325
docs/dev.md Normal file
View file

@ -0,0 +1,325 @@
# core dev
Portable development environment with 100+ embedded tools.
## Overview
Core DevOps provides a sandboxed, immutable development environment based on LinuxKit. It includes AI tools (Claude, Gemini), runtimes (Go, Node, PHP, Python, Rust), and infrastructure tools (Docker, Kubernetes, Terraform).
## Commands
| Command | Description |
|---------|-------------|
| `install` | Download the core-devops image for your platform |
| `boot` | Start the development environment |
| `stop` | Stop the running environment |
| `status` | Show environment status |
| `shell` | Open a shell in the environment |
| `serve` | Mount project and start dev server |
| `test` | Run tests inside the environment |
| `claude` | Start sandboxed Claude session |
| `update` | Update to latest image |
## Quick Start
```bash
# First time setup
core dev install
core dev boot
# Open shell
core dev shell
# Or mount current project and serve
core dev serve
```
## dev install
Download the core-devops image for your platform.
```bash
core dev install [flags]
```
### Flags
| Flag | Description |
|------|-------------|
| `--source` | Image source: `github`, `registry`, `cdn` (default: auto) |
| `--force` | Force re-download even if exists |
### Examples
```bash
# Download image (auto-detects platform)
core dev install
# Force re-download
core dev install --force
```
## dev boot
Start the development environment.
```bash
core dev boot [flags]
```
### Flags
| Flag | Description |
|------|-------------|
| `--memory` | Memory allocation in MB (default: 4096) |
| `--cpus` | Number of CPUs (default: 4) |
| `--name` | Container name (default: core-dev) |
### Examples
```bash
# Start with defaults
core dev boot
# More resources
core dev boot --memory 8192 --cpus 8
```
## dev shell
Open a shell in the running environment.
```bash
core dev shell [flags]
```
### Flags
| Flag | Description |
|------|-------------|
| `--console` | Use serial console instead of SSH |
### Examples
```bash
# SSH into environment
core dev shell
# Serial console (for debugging)
core dev shell --console
```
## dev serve
Mount current directory and start the appropriate dev server.
```bash
core dev serve [flags]
```
### Flags
| Flag | Description |
|------|-------------|
| `--port` | Port to expose (default: 8000) |
| `--path` | Subdirectory to serve |
### Auto-Detection
| Project | Server Command |
|---------|---------------|
| Laravel (`artisan`) | `php artisan octane:start` |
| Node (`package.json` with `dev` script) | `npm run dev` |
| PHP (`composer.json`) | `frankenphp php-server` |
| Other | `python -m http.server` |
### Examples
```bash
# Auto-detect and serve
core dev serve
# Custom port
core dev serve --port 3000
```
## dev test
Run tests inside the environment.
```bash
core dev test [flags] [-- custom command]
```
### Flags
| Flag | Description |
|------|-------------|
| `--unit` | Run only unit tests |
### Test Detection
Core auto-detects the test framework:
1. `.core/test.yaml` - Custom config
2. `composer.json` → `composer test`
3. `package.json` → `npm test`
4. `go.mod` → `go test ./...`
5. `pytest.ini` → `pytest`
6. `Taskfile.yaml` → `task test`
### Examples
```bash
# Auto-detect and run tests
core dev test
# Custom command
core dev test -- go test -v ./pkg/...
```
### Test Configuration
Create `.core/test.yaml` for custom test setup:
```yaml
version: 1
commands:
- name: unit
run: vendor/bin/pest --parallel
- name: types
run: vendor/bin/phpstan analyse
- name: lint
run: vendor/bin/pint --test
env:
APP_ENV: testing
DB_CONNECTION: sqlite
```
## dev claude
Start a sandboxed Claude session with your project mounted.
```bash
core dev claude [flags]
```
### Flags
| Flag | Description |
|------|-------------|
| `--no-auth` | Clean session without host credentials |
| `--auth` | Selective auth forwarding (e.g., `gh,anthropic`) |
### What Gets Forwarded
By default, these are forwarded to the sandbox:
- `~/.anthropic/` or `ANTHROPIC_API_KEY`
- `~/.config/gh/` (GitHub CLI auth)
- SSH agent
- Git config (name, email)
### Examples
```bash
# Full auth forwarding (default)
core dev claude
# Clean sandbox
core dev claude --no-auth
# Only GitHub auth
core dev claude --auth=gh
```
### Why Use This?
- **Immutable base** - Reset anytime with `core dev boot --fresh`
- **Safe experimentation** - Claude can install packages, make mistakes
- **Host system untouched** - All changes stay in the sandbox
- **Real credentials** - Can still push code, create PRs
- **Full tooling** - 100+ tools available in the image
## dev status
Show the current state of the development environment.
```bash
core dev status
```
Output includes:
- Running/stopped state
- Resource usage (CPU, memory)
- Exposed ports
- Mounted directories
## dev update
Check for and download newer images.
```bash
core dev update [flags]
```
### Flags
| Flag | Description |
|------|-------------|
| `--force` | Force download even if up to date |
## Embedded Tools
The core-devops image includes 100+ tools:
| Category | Tools |
|----------|-------|
| **AI/LLM** | claude, gemini, aider, ollama, llm |
| **VCS** | git, gh, glab, lazygit, delta, git-lfs |
| **Runtimes** | frankenphp, node, bun, deno, go, python3, rustc |
| **Package Mgrs** | composer, npm, pnpm, yarn, pip, uv, cargo |
| **Build** | task, make, just, nx, turbo |
| **Linting** | pint, phpstan, prettier, eslint, biome, golangci-lint, ruff |
| **Testing** | phpunit, pest, vitest, playwright, k6 |
| **Infra** | docker, kubectl, k9s, helm, terraform, ansible |
| **Databases** | sqlite3, mysql, psql, redis-cli, mongosh, usql |
| **HTTP/Net** | curl, httpie, xh, websocat, grpcurl, mkcert, ngrok |
| **Data** | jq, yq, fx, gron, miller, dasel |
| **Security** | age, sops, cosign, trivy, trufflehog, vault |
| **Files** | fd, rg, fzf, bat, eza, tree, zoxide, broot |
| **Editors** | nvim, helix, micro |
## Configuration
Global config in `~/.core/config.yaml`:
```yaml
version: 1
images:
source: auto # auto | github | registry | cdn
cdn:
url: https://images.example.com/core-devops
github:
repo: host-uk/core-images
registry:
image: ghcr.io/host-uk/core-devops
```
## Image Storage
Images are stored in `~/.core/images/`:
```
~/.core/
├── config.yaml
└── images/
├── core-devops-darwin-arm64.qcow2
├── core-devops-linux-amd64.qcow2
└── manifest.json
```

75
docs/doctor.md Normal file
View file

@ -0,0 +1,75 @@
# core doctor
Check your development environment for required tools and configuration.
## Usage
```bash
core doctor
```
## What It Checks
### Required Tools
| Tool | Purpose |
|------|---------|
| `git` | Version control |
| `go` | Go compiler |
| `gh` | GitHub CLI |
### Optional Tools
| Tool | Purpose |
|------|---------|
| `node` | Node.js runtime |
| `docker` | Container runtime |
| `wails` | Desktop app framework |
| `qemu` | VM runtime for LinuxKit |
| `gpg` | Code signing |
| `codesign` | macOS signing (macOS only) |
### Configuration
- Git user name and email
- GitHub CLI authentication
- Go workspace setup
## Output
```
Core Doctor
===========
Required:
[OK] git 2.43.0
[OK] go 1.23.0
[OK] gh 2.40.0
Optional:
[OK] node 20.10.0
[OK] docker 24.0.7
[--] wails (not installed)
[OK] qemu 8.2.0
[OK] gpg 2.4.3
[OK] codesign (available)
Configuration:
[OK] git user.name: Your Name
[OK] git user.email: you@example.com
[OK] gh auth status: Logged in
All checks passed!
```
## Exit Codes
| Code | Meaning |
|------|---------|
| 0 | All required checks passed |
| 1 | One or more required checks failed |
## See Also
- [setup command](setup.md) - Clone repos from registry
- [dev install](dev.md) - Install development environment

41
docs/index.md
View file

@ -14,16 +14,40 @@ curl -fsSL https://github.com/host-uk/core/releases/latest/download/core-$(uname
## Commands
### Build & Release
| Command | Description |
|---------|-------------|
| `core build` | Build Go, Wails, Docker, and LinuxKit projects |
| `core release` | Build and publish to GitHub, npm, Homebrew, etc. |
| `core sdk` | Generate and manage API SDKs |
### Containers
| Command | Description |
|---------|-------------|
| `core run` | Run LinuxKit images with qemu/hyperkit |
| `core php` | Laravel/PHP development environment |
| `core ps` | List running containers |
| `core stop` | Stop running containers |
| `core logs` | View container logs |
| `core exec` | Execute commands in containers |
| `core templates` | Manage LinuxKit templates |
### Development
| Command | Description |
|---------|-------------|
| `core dev` | Portable development environment (100+ tools) |
| `core php` | Laravel/PHP development tools |
| `core doctor` | Check development environment |
### GitHub Integration
| Command | Description |
|---------|-------------|
| `core search` | Search GitHub for repositories |
| `core install` | Clone a repository from GitHub |
| `core setup` | Clone all repos from registry |
## Quick Start
@ -61,10 +85,21 @@ Core uses `.core/` directory for project configuration:
## Documentation
- [Build Command](build.md) - Cross-platform builds
### Build & Release
- [Build Command](build.md) - Cross-platform builds with code signing
- [Release Command](release.md) - Publishing to package managers
- [PHP Commands](php.md) - Laravel development
- [SDK Command](sdk.md) - Generate API clients from OpenAPI
### Containers
- [Run Command](run.md) - Container management
### Development
- [Dev Command](dev.md) - Portable development environment
- [PHP Commands](php.md) - Laravel development
- [Doctor Command](doctor.md) - Environment check
- [Search & Install](search.md) - GitHub integration
### Reference
- [Configuration](configuration.md) - All config options
- [Examples](examples/) - Sample configurations

30
docs/release.md
View file

@ -14,7 +14,9 @@ core release [flags]
|------|-------------|
| `--dry-run` | Preview what would be published |
| `--version` | Override version (default: git tag) |
| `--skip-build` | Skip build, use existing artifacts |
| `--target` | Release target: `sdk` for SDK-only release |
| `--draft` | Create release as draft |
| `--prerelease` | Mark release as prerelease |
## Quick Start
@ -27,8 +29,34 @@ core release --dry-run
# Release
core release
# SDK-only release
core release --target sdk
```
## SDK Release
Generate SDKs without building binaries:
```bash
# Generate SDKs with version from git tag
core release --target sdk
# Explicit version
core release --target sdk --version v1.2.3
# Preview
core release --target sdk --dry-run
```
This will:
1. Determine version from git tags (or `--version` flag)
2. Run breaking change detection if configured
3. Generate SDKs for all configured languages
4. Output to `sdk/` directory
See [SDK commands](sdk.md) for more details.
## Publishers
### GitHub Releases

188
docs/sdk.md Normal file
View file

@ -0,0 +1,188 @@
# core sdk
Generate typed API clients from OpenAPI specifications.
## Usage
```bash
core sdk <command> [flags]
```
## Commands
| Command | Description |
|---------|-------------|
| `generate` | Generate SDKs from OpenAPI spec |
| `validate` | Validate OpenAPI spec |
| `diff` | Check for breaking API changes |
## sdk generate
Generate typed API clients for multiple languages.
```bash
core sdk generate [flags]
```
### Flags
| Flag | Description |
|------|-------------|
| `--spec` | Path to OpenAPI spec file (auto-detected) |
| `--lang` | Generate only this language |
### Examples
```bash
# Generate all configured SDKs
core sdk generate
# Generate only TypeScript SDK
core sdk generate --lang typescript
# Use specific spec file
core sdk generate --spec api/openapi.yaml
```
### Supported Languages
| Language | Generator |
|----------|-----------|
| TypeScript | openapi-generator (typescript-fetch) |
| Python | openapi-generator (python) |
| Go | openapi-generator (go) |
| PHP | openapi-generator (php) |
## sdk validate
Validate an OpenAPI specification file.
```bash
core sdk validate [flags]
```
### Flags
| Flag | Description |
|------|-------------|
| `--spec` | Path to OpenAPI spec file (auto-detected) |
### Examples
```bash
# Validate detected spec
core sdk validate
# Validate specific file
core sdk validate --spec api/openapi.yaml
```
## sdk diff
Check for breaking changes between API versions.
```bash
core sdk diff [flags]
```
### Flags
| Flag | Description |
|------|-------------|
| `--base` | Base spec version (git tag or file path) |
| `--spec` | Current spec file (auto-detected) |
### Examples
```bash
# Compare against previous release
core sdk diff --base v1.0.0
# Compare two files
core sdk diff --base old-api.yaml --spec new-api.yaml
```
### Breaking Changes Detected
- Removed endpoints
- Changed parameter types
- Removed required fields
- Changed response types
## Release Integration
Generate SDKs as part of the release process:
```bash
# Generate SDKs for release
core release --target sdk
# With explicit version
core release --target sdk --version v1.2.3
# Preview what would be generated
core release --target sdk --dry-run
```
See [release command](release.md) for full details.
## Configuration
Configure SDK generation in `.core/release.yaml`:
```yaml
sdk:
# OpenAPI spec path (auto-detected if not set)
spec: api/openapi.yaml
# Languages to generate
languages:
- typescript
- python
- go
- php
# Output directory
output: sdk
# Package naming
package:
name: my-api-sdk
# Breaking change detection
diff:
enabled: true
fail_on_breaking: false # Warn but continue
```
## Spec Auto-Detection
Core looks for OpenAPI specs in this order:
1. Path specified in config (`sdk.spec`)
2. `openapi.yaml` / `openapi.json`
3. `api/openapi.yaml` / `api/openapi.json`
4. `docs/openapi.yaml` / `docs/openapi.json`
5. Laravel Scramble endpoint (`/docs/api.json`)
## Output Structure
Generated SDKs are placed in language-specific directories:
```
sdk/
├── typescript/
│ ├── src/
│ ├── package.json
│ └── tsconfig.json
├── python/
│ ├── my_api_sdk/
│ ├── setup.py
│ └── requirements.txt
├── go/
│ ├── client.go
│ └── go.mod
└── php/
├── src/
└── composer.json
```

112
docs/search.md Normal file
View file

@ -0,0 +1,112 @@
# core search & install
Search GitHub for repositories and install them locally.
## core search
Search GitHub for repositories matching a pattern.
```bash
core search <pattern> [flags]
```
### Flags
| Flag | Description |
|------|-------------|
| `--org` | Search within a specific organization |
| `--limit` | Maximum results (default: 10) |
| `--language` | Filter by programming language |
### Examples
```bash
# Search by pattern
core search "cli tool"
# Search within organization
core search --org host-uk
# Search with language filter
core search --org host-uk --language go
# Search all core-* repos
core search "core-" --org host-uk
```
### Output
```
Found 5 repositories:
host-uk/core
Go CLI for the host-uk ecosystem
★ 42 Go Updated 2 hours ago
host-uk/core-php
PHP/Laravel packages for Core
★ 18 PHP Updated 1 day ago
host-uk/core-images
Docker and LinuxKit images
★ 8 Dockerfile Updated 3 days ago
```
## core install
Clone a repository from GitHub.
```bash
core install <repo> [flags]
```
### Flags
| Flag | Description |
|------|-------------|
| `--path` | Destination directory (default: current dir) |
| `--branch` | Clone specific branch |
| `--depth` | Shallow clone depth |
### Examples
```bash
# Install by full name
core install host-uk/core
# Install to specific path
core install host-uk/core --path ~/Code/host-uk
# Install specific branch
core install host-uk/core --branch dev
# Shallow clone
core install host-uk/core --depth 1
```
### Authentication
Uses GitHub CLI (`gh`) authentication. Ensure you're logged in:
```bash
gh auth status
gh auth login # if not authenticated
```
## Workflow Example
```bash
# Find repositories
core search --org host-uk
# Install one
core install host-uk/core-php --path ~/Code/host-uk
# Check setup
core doctor
```
## See Also
- [setup command](setup.md) - Clone all repos from registry
- [doctor command](doctor.md) - Check environment